qemu/qemu-doc.texi
<<
>>
Prefs
   1\input texinfo @c -*- texinfo -*-
   2@c %**start of header
   3@setfilename qemu-doc.info
   4@include version.texi
   5
   6@documentlanguage en
   7@documentencoding UTF-8
   8
   9@settitle QEMU version @value{VERSION} User Documentation
  10@exampleindent 0
  11@paragraphindent 0
  12@c %**end of header
  13
  14@ifinfo
  15@direntry
  16* QEMU: (qemu-doc).    The QEMU Emulator User Documentation.
  17@end direntry
  18@end ifinfo
  19
  20@iftex
  21@titlepage
  22@sp 7
  23@center @titlefont{QEMU version @value{VERSION}}
  24@sp 1
  25@center @titlefont{User Documentation}
  26@sp 3
  27@end titlepage
  28@end iftex
  29
  30@ifnottex
  31@node Top
  32@top
  33
  34@menu
  35* Introduction::
  36* QEMU PC System emulator::
  37* QEMU System emulator for non PC targets::
  38* QEMU Guest Agent::
  39* QEMU User space emulator::
  40* System requirements::
  41* Security::
  42* Implementation notes::
  43* Deprecated features::
  44* Supported build platforms::
  45* License::
  46* Index::
  47@end menu
  48@end ifnottex
  49
  50@contents
  51
  52@node Introduction
  53@chapter Introduction
  54
  55@menu
  56* intro_features:: Features
  57@end menu
  58
  59@node intro_features
  60@section Features
  61
  62QEMU is a FAST! processor emulator using dynamic translation to
  63achieve good emulation speed.
  64
  65@cindex operating modes
  66QEMU has two operating modes:
  67
  68@itemize
  69@cindex system emulation
  70@item Full system emulation. In this mode, QEMU emulates a full system (for
  71example a PC), including one or several processors and various
  72peripherals. It can be used to launch different Operating Systems
  73without rebooting the PC or to debug system code.
  74
  75@cindex user mode emulation
  76@item User mode emulation. In this mode, QEMU can launch
  77processes compiled for one CPU on another CPU. It can be used to
  78launch the Wine Windows API emulator (@url{https://www.winehq.org}) or
  79to ease cross-compilation and cross-debugging.
  80
  81@end itemize
  82
  83QEMU has the following features:
  84
  85@itemize
  86@item QEMU can run without a host kernel driver and yet gives acceptable
  87performance.  It uses dynamic translation to native code for reasonable speed,
  88with support for self-modifying code and precise exceptions.
  89
  90@item It is portable to several operating systems (GNU/Linux, *BSD, Mac OS X,
  91Windows) and architectures.
  92
  93@item It performs accurate software emulation of the FPU.
  94@end itemize
  95
  96QEMU user mode emulation has the following features:
  97@itemize
  98@item Generic Linux system call converter, including most ioctls.
  99
 100@item clone() emulation using native CPU clone() to use Linux scheduler for threads.
 101
 102@item Accurate signal handling by remapping host signals to target signals.
 103@end itemize
 104
 105QEMU full system emulation has the following features:
 106@itemize
 107@item
 108QEMU uses a full software MMU for maximum portability.
 109
 110@item
 111QEMU can optionally use an in-kernel accelerator, like kvm. The accelerators
 112execute most of the guest code natively, while
 113continuing to emulate the rest of the machine.
 114
 115@item
 116Various hardware devices can be emulated and in some cases, host
 117devices (e.g. serial and parallel ports, USB, drives) can be used
 118transparently by the guest Operating System. Host device passthrough
 119can be used for talking to external physical peripherals (e.g. a
 120webcam, modem or tape drive).
 121
 122@item
 123Symmetric multiprocessing (SMP) support.  Currently, an in-kernel
 124accelerator is required to use more than one host CPU for emulation.
 125
 126@end itemize
 127
 128
 129@node QEMU PC System emulator
 130@chapter QEMU PC System emulator
 131@cindex system emulation (PC)
 132
 133@menu
 134* pcsys_introduction:: Introduction
 135* pcsys_quickstart::   Quick Start
 136* sec_invocation::     Invocation
 137* pcsys_keys::         Keys in the graphical frontends
 138* mux_keys::           Keys in the character backend multiplexer
 139* pcsys_monitor::      QEMU Monitor
 140* cpu_models::         CPU models
 141* disk_images::        Disk Images
 142* pcsys_network::      Network emulation
 143* pcsys_other_devs::   Other Devices
 144* direct_linux_boot::  Direct Linux Boot
 145* pcsys_usb::          USB emulation
 146* vnc_security::       VNC security
 147* network_tls::        TLS setup for network services
 148* gdb_usage::          GDB usage
 149* pcsys_os_specific::  Target OS specific information
 150@end menu
 151
 152@node pcsys_introduction
 153@section Introduction
 154
 155@c man begin DESCRIPTION
 156
 157The QEMU PC System emulator simulates the
 158following peripherals:
 159
 160@itemize @minus
 161@item
 162i440FX host PCI bridge and PIIX3 PCI to ISA bridge
 163@item
 164Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
 165extensions (hardware level, including all non standard modes).
 166@item
 167PS/2 mouse and keyboard
 168@item
 1692 PCI IDE interfaces with hard disk and CD-ROM support
 170@item
 171Floppy disk
 172@item
 173PCI and ISA network adapters
 174@item
 175Serial ports
 176@item
 177IPMI BMC, either and internal or external one
 178@item
 179Creative SoundBlaster 16 sound card
 180@item
 181ENSONIQ AudioPCI ES1370 sound card
 182@item
 183Intel 82801AA AC97 Audio compatible sound card
 184@item
 185Intel HD Audio Controller and HDA codec
 186@item
 187Adlib (OPL2) - Yamaha YM3812 compatible chip
 188@item
 189Gravis Ultrasound GF1 sound card
 190@item
 191CS4231A compatible sound card
 192@item
 193PCI UHCI, OHCI, EHCI or XHCI USB controller and a virtual USB-1.1 hub.
 194@end itemize
 195
 196SMP is supported with up to 255 CPUs.
 197
 198QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL
 199VGA BIOS.
 200
 201QEMU uses YM3812 emulation by Tatsuyuki Satoh.
 202
 203QEMU uses GUS emulation (GUSEMU32 @url{http://www.deinmeister.de/gusemu/})
 204by Tibor "TS" Schütz.
 205
 206Note that, by default, GUS shares IRQ(7) with parallel ports and so
 207QEMU must be told to not have parallel ports to have working GUS.
 208
 209@example
 210qemu-system-i386 dos.img -soundhw gus -parallel none
 211@end example
 212
 213Alternatively:
 214@example
 215qemu-system-i386 dos.img -device gus,irq=5
 216@end example
 217
 218Or some other unclaimed IRQ.
 219
 220CS4231A is the chip used in Windows Sound System and GUSMAX products
 221
 222@c man end
 223
 224@node pcsys_quickstart
 225@section Quick Start
 226@cindex quick start
 227
 228Download and uncompress the linux image (@file{linux.img}) and type:
 229
 230@example
 231qemu-system-i386 linux.img
 232@end example
 233
 234Linux should boot and give you a prompt.
 235
 236@node sec_invocation
 237@section Invocation
 238
 239@example
 240@c man begin SYNOPSIS
 241@command{qemu-system-i386} [@var{options}] [@var{disk_image}]
 242@c man end
 243@end example
 244
 245@c man begin OPTIONS
 246@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some
 247targets do not need a disk image.
 248
 249@include qemu-options.texi
 250
 251@c man end
 252
 253@subsection Device URL Syntax
 254@c TODO merge this with section Disk Images
 255
 256@c man begin NOTES
 257
 258In addition to using normal file images for the emulated storage devices,
 259QEMU can also use networked resources such as iSCSI devices. These are
 260specified using a special URL syntax.
 261
 262@table @option
 263@item iSCSI
 264iSCSI support allows QEMU to access iSCSI resources directly and use as
 265images for the guest storage. Both disk and cdrom images are supported.
 266
 267Syntax for specifying iSCSI LUNs is
 268``iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>''
 269
 270By default qemu will use the iSCSI initiator-name
 271'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from the command
 272line or a configuration file.
 273
 274Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect
 275stalled requests and force a reestablishment of the session. The timeout
 276is specified in seconds. The default is 0 which means no timeout. Libiscsi
 2771.15.0 or greater is required for this feature.
 278
 279Example (without authentication):
 280@example
 281qemu-system-i386 -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
 282                 -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
 283                 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
 284@end example
 285
 286Example (CHAP username/password via URL):
 287@example
 288qemu-system-i386 -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1
 289@end example
 290
 291Example (CHAP username/password via environment variables):
 292@example
 293LIBISCSI_CHAP_USERNAME="user" \
 294LIBISCSI_CHAP_PASSWORD="password" \
 295qemu-system-i386 -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
 296@end example
 297
 298@item NBD
 299QEMU supports NBD (Network Block Devices) both using TCP protocol as well
 300as Unix Domain Sockets.
 301
 302Syntax for specifying a NBD device using TCP
 303``nbd:<server-ip>:<port>[:exportname=<export>]''
 304
 305Syntax for specifying a NBD device using Unix Domain Sockets
 306``nbd:unix:<domain-socket>[:exportname=<export>]''
 307
 308Example for TCP
 309@example
 310qemu-system-i386 --drive file=nbd:192.0.2.1:30000
 311@end example
 312
 313Example for Unix Domain Sockets
 314@example
 315qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket
 316@end example
 317
 318@item SSH
 319QEMU supports SSH (Secure Shell) access to remote disks.
 320
 321Examples:
 322@example
 323qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img
 324qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
 325@end example
 326
 327Currently authentication must be done using ssh-agent.  Other
 328authentication methods may be supported in future.
 329
 330@item Sheepdog
 331Sheepdog is a distributed storage system for QEMU.
 332QEMU supports using either local sheepdog devices or remote networked
 333devices.
 334
 335Syntax for specifying a sheepdog device
 336@example
 337sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
 338@end example
 339
 340Example
 341@example
 342qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
 343@end example
 344
 345See also @url{https://sheepdog.github.io/sheepdog/}.
 346
 347@item GlusterFS
 348GlusterFS is a user space distributed file system.
 349QEMU supports the use of GlusterFS volumes for hosting VM disk images using
 350TCP, Unix Domain Sockets and RDMA transport protocols.
 351
 352Syntax for specifying a VM disk image on GlusterFS volume is
 353@example
 354
 355URI:
 356gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
 357
 358JSON:
 359'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
 360@                                 "server":[@{"type":"tcp","host":"...","port":"..."@},
 361@                                           @{"type":"unix","socket":"..."@}]@}@}'
 362@end example
 363
 364
 365Example
 366@example
 367URI:
 368qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img,
 369@                               file.debug=9,file.logfile=/var/log/qemu-gluster.log
 370
 371JSON:
 372qemu-system-x86_64 'json:@{"driver":"qcow2",
 373@                          "file":@{"driver":"gluster",
 374@                                   "volume":"testvol","path":"a.img",
 375@                                   "debug":9,"logfile":"/var/log/qemu-gluster.log",
 376@                                   "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
 377@                                             @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
 378qemu-system-x86_64 -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
 379@                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log,
 380@                                      file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
 381@                                      file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
 382@end example
 383
 384See also @url{http://www.gluster.org}.
 385
 386@item HTTP/HTTPS/FTP/FTPS
 387QEMU supports read-only access to files accessed over http(s) and ftp(s).
 388
 389Syntax using a single filename:
 390@example
 391<protocol>://[<username>[:<password>]@@]<host>/<path>
 392@end example
 393
 394where:
 395@table @option
 396@item protocol
 397'http', 'https', 'ftp', or 'ftps'.
 398
 399@item username
 400Optional username for authentication to the remote server.
 401
 402@item password
 403Optional password for authentication to the remote server.
 404
 405@item host
 406Address of the remote server.
 407
 408@item path
 409Path on the remote server, including any query string.
 410@end table
 411
 412The following options are also supported:
 413@table @option
 414@item url
 415The full URL when passing options to the driver explicitly.
 416
 417@item readahead
 418The amount of data to read ahead with each range request to the remote server.
 419This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it
 420does not have a suffix, it will be assumed to be in bytes. The value must be a
 421multiple of 512 bytes. It defaults to 256k.
 422
 423@item sslverify
 424Whether to verify the remote server's certificate when connecting over SSL. It
 425can have the value 'on' or 'off'. It defaults to 'on'.
 426
 427@item cookie
 428Send this cookie (it can also be a list of cookies separated by ';') with
 429each outgoing request.  Only supported when using protocols such as HTTP
 430which support cookies, otherwise ignored.
 431
 432@item timeout
 433Set the timeout in seconds of the CURL connection. This timeout is the time
 434that CURL waits for a response from the remote server to get the size of the
 435image to be downloaded. If not set, the default timeout of 5 seconds is used.
 436@end table
 437
 438Note that when passing options to qemu explicitly, @option{driver} is the value
 439of <protocol>.
 440
 441Example: boot from a remote Fedora 20 live ISO image
 442@example
 443qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
 444
 445qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
 446@end example
 447
 448Example: boot from a remote Fedora 20 cloud image using a local overlay for
 449writes, copy-on-read, and a readahead of 64k
 450@example
 451qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
 452
 453qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
 454@end example
 455
 456Example: boot from an image stored on a VMware vSphere server with a self-signed
 457certificate using a local overlay for writes, a readahead of 64k and a timeout
 458of 10 seconds.
 459@example
 460qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2
 461
 462qemu-system-x86_64 -drive file=/tmp/test.qcow2
 463@end example
 464
 465@end table
 466
 467@c man end
 468
 469@node pcsys_keys
 470@section Keys in the graphical frontends
 471
 472@c man begin OPTIONS
 473
 474During the graphical emulation, you can use special key combinations to change
 475modes. The default key mappings are shown below, but if you use @code{-alt-grab}
 476then the modifier is Ctrl-Alt-Shift (instead of Ctrl-Alt) and if you use
 477@code{-ctrl-grab} then the modifier is the right Ctrl key (instead of Ctrl-Alt):
 478
 479@table @key
 480@item Ctrl-Alt-f
 481@kindex Ctrl-Alt-f
 482Toggle full screen
 483
 484@item Ctrl-Alt-+
 485@kindex Ctrl-Alt-+
 486Enlarge the screen
 487
 488@item Ctrl-Alt--
 489@kindex Ctrl-Alt--
 490Shrink the screen
 491
 492@item Ctrl-Alt-u
 493@kindex Ctrl-Alt-u
 494Restore the screen's un-scaled dimensions
 495
 496@item Ctrl-Alt-n
 497@kindex Ctrl-Alt-n
 498Switch to virtual console 'n'. Standard console mappings are:
 499@table @emph
 500@item 1
 501Target system display
 502@item 2
 503Monitor
 504@item 3
 505Serial port
 506@end table
 507
 508@item Ctrl-Alt
 509@kindex Ctrl-Alt
 510Toggle mouse and keyboard grab.
 511@end table
 512
 513@kindex Ctrl-Up
 514@kindex Ctrl-Down
 515@kindex Ctrl-PageUp
 516@kindex Ctrl-PageDown
 517In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down},
 518@key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log.
 519
 520@c man end
 521
 522@node mux_keys
 523@section Keys in the character backend multiplexer
 524
 525@c man begin OPTIONS
 526
 527During emulation, if you are using a character backend multiplexer
 528(which is the default if you are using @option{-nographic}) then
 529several commands are available via an escape sequence. These
 530key sequences all start with an escape character, which is @key{Ctrl-a}
 531by default, but can be changed with @option{-echr}. The list below assumes
 532you're using the default.
 533
 534@table @key
 535@item Ctrl-a h
 536@kindex Ctrl-a h
 537Print this help
 538@item Ctrl-a x
 539@kindex Ctrl-a x
 540Exit emulator
 541@item Ctrl-a s
 542@kindex Ctrl-a s
 543Save disk data back to file (if -snapshot)
 544@item Ctrl-a t
 545@kindex Ctrl-a t
 546Toggle console timestamps
 547@item Ctrl-a b
 548@kindex Ctrl-a b
 549Send break (magic sysrq in Linux)
 550@item Ctrl-a c
 551@kindex Ctrl-a c
 552Rotate between the frontends connected to the multiplexer (usually
 553this switches between the monitor and the console)
 554@item Ctrl-a Ctrl-a
 555@kindex Ctrl-a Ctrl-a
 556Send the escape character to the frontend
 557@end table
 558@c man end
 559
 560@ignore
 561
 562@c man begin SEEALSO
 563The HTML documentation of QEMU for more precise information and Linux
 564user mode emulator invocation.
 565@c man end
 566
 567@c man begin AUTHOR
 568Fabrice Bellard
 569@c man end
 570
 571@end ignore
 572
 573@node pcsys_monitor
 574@section QEMU Monitor
 575@cindex QEMU monitor
 576
 577The QEMU monitor is used to give complex commands to the QEMU
 578emulator. You can use it to:
 579
 580@itemize @minus
 581
 582@item
 583Remove or insert removable media images
 584(such as CD-ROM or floppies).
 585
 586@item
 587Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
 588from a disk file.
 589
 590@item Inspect the VM state without an external debugger.
 591
 592@end itemize
 593
 594@subsection Commands
 595
 596The following commands are available:
 597
 598@include qemu-monitor.texi
 599
 600@include qemu-monitor-info.texi
 601
 602@subsection Integer expressions
 603
 604The monitor understands integers expressions for every integer
 605argument. You can use register names to get the value of specifics
 606CPU registers by prefixing them with @emph{$}.
 607
 608@node cpu_models
 609@section CPU models
 610
 611@include docs/qemu-cpu-models.texi
 612
 613@node disk_images
 614@section Disk Images
 615
 616QEMU supports many disk image formats, including growable disk images
 617(their size increase as non empty sectors are written), compressed and
 618encrypted disk images.
 619
 620@menu
 621* disk_images_quickstart::    Quick start for disk image creation
 622* disk_images_snapshot_mode:: Snapshot mode
 623* vm_snapshots::              VM snapshots
 624* qemu_img_invocation::       qemu-img Invocation
 625* qemu_nbd_invocation::       qemu-nbd Invocation
 626* disk_images_formats::       Disk image file formats
 627* host_drives::               Using host drives
 628* disk_images_fat_images::    Virtual FAT disk images
 629* disk_images_nbd::           NBD access
 630* disk_images_sheepdog::      Sheepdog disk images
 631* disk_images_iscsi::         iSCSI LUNs
 632* disk_images_gluster::       GlusterFS disk images
 633* disk_images_ssh::           Secure Shell (ssh) disk images
 634* disk_images_nvme::          NVMe userspace driver
 635* disk_image_locking::        Disk image file locking
 636@end menu
 637
 638@node disk_images_quickstart
 639@subsection Quick start for disk image creation
 640
 641You can create a disk image with the command:
 642@example
 643qemu-img create myimage.img mysize
 644@end example
 645where @var{myimage.img} is the disk image filename and @var{mysize} is its
 646size in kilobytes. You can add an @code{M} suffix to give the size in
 647megabytes and a @code{G} suffix for gigabytes.
 648
 649See @ref{qemu_img_invocation} for more information.
 650
 651@node disk_images_snapshot_mode
 652@subsection Snapshot mode
 653
 654If you use the option @option{-snapshot}, all disk images are
 655considered as read only. When sectors in written, they are written in
 656a temporary file created in @file{/tmp}. You can however force the
 657write back to the raw disk images by using the @code{commit} monitor
 658command (or @key{C-a s} in the serial console).
 659
 660@node vm_snapshots
 661@subsection VM snapshots
 662
 663VM snapshots are snapshots of the complete virtual machine including
 664CPU state, RAM, device state and the content of all the writable
 665disks. In order to use VM snapshots, you must have at least one non
 666removable and writable block device using the @code{qcow2} disk image
 667format. Normally this device is the first virtual hard drive.
 668
 669Use the monitor command @code{savevm} to create a new VM snapshot or
 670replace an existing one. A human readable name can be assigned to each
 671snapshot in addition to its numerical ID.
 672
 673Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
 674a VM snapshot. @code{info snapshots} lists the available snapshots
 675with their associated information:
 676
 677@example
 678(qemu) info snapshots
 679Snapshot devices: hda
 680Snapshot list (from hda):
 681ID        TAG                 VM SIZE                DATE       VM CLOCK
 6821         start                   41M 2006-08-06 12:38:02   00:00:14.954
 6832                                 40M 2006-08-06 12:43:29   00:00:18.633
 6843         msys                    40M 2006-08-06 12:44:04   00:00:23.514
 685@end example
 686
 687A VM snapshot is made of a VM state info (its size is shown in
 688@code{info snapshots}) and a snapshot of every writable disk image.
 689The VM state info is stored in the first @code{qcow2} non removable
 690and writable block device. The disk image snapshots are stored in
 691every disk image. The size of a snapshot in a disk image is difficult
 692to evaluate and is not shown by @code{info snapshots} because the
 693associated disk sectors are shared among all the snapshots to save
 694disk space (otherwise each snapshot would need a full copy of all the
 695disk images).
 696
 697When using the (unrelated) @code{-snapshot} option
 698(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
 699but they are deleted as soon as you exit QEMU.
 700
 701VM snapshots currently have the following known limitations:
 702@itemize
 703@item
 704They cannot cope with removable devices if they are removed or
 705inserted after a snapshot is done.
 706@item
 707A few device drivers still have incomplete snapshot support so their
 708state is not saved or restored properly (in particular USB).
 709@end itemize
 710
 711@node qemu_img_invocation
 712@subsection @code{qemu-img} Invocation
 713
 714@include qemu-img.texi
 715
 716@node qemu_nbd_invocation
 717@subsection @code{qemu-nbd} Invocation
 718
 719@include qemu-nbd.texi
 720
 721@include docs/qemu-block-drivers.texi
 722
 723@node pcsys_network
 724@section Network emulation
 725
 726QEMU can simulate several network cards (e.g. PCI or ISA cards on the PC
 727target) and can connect them to a network backend on the host or an emulated
 728hub. The various host network backends can either be used to connect the NIC of
 729the guest to a real network (e.g. by using a TAP devices or the non-privileged
 730user mode network stack), or to other guest instances running in another QEMU
 731process (e.g. by using the socket host network backend).
 732
 733@subsection Using TAP network interfaces
 734
 735This is the standard way to connect QEMU to a real network. QEMU adds
 736a virtual network device on your host (called @code{tapN}), and you
 737can then configure it as if it was a real ethernet card.
 738
 739@subsubsection Linux host
 740
 741As an example, you can download the @file{linux-test-xxx.tar.gz}
 742archive and copy the script @file{qemu-ifup} in @file{/etc} and
 743configure properly @code{sudo} so that the command @code{ifconfig}
 744contained in @file{qemu-ifup} can be executed as root. You must verify
 745that your host kernel supports the TAP network interfaces: the
 746device @file{/dev/net/tun} must be present.
 747
 748See @ref{sec_invocation} to have examples of command lines using the
 749TAP network interfaces.
 750
 751@subsubsection Windows host
 752
 753There is a virtual ethernet driver for Windows 2000/XP systems, called
 754TAP-Win32. But it is not included in standard QEMU for Windows,
 755so you will need to get it separately. It is part of OpenVPN package,
 756so download OpenVPN from : @url{https://openvpn.net/}.
 757
 758@subsection Using the user mode network stack
 759
 760By using the option @option{-net user} (default configuration if no
 761@option{-net} option is specified), QEMU uses a completely user mode
 762network stack (you don't need root privilege to use the virtual
 763network). The virtual network configuration is the following:
 764
 765@example
 766
 767     guest (10.0.2.15)  <------>  Firewall/DHCP server <-----> Internet
 768                           |          (10.0.2.2)
 769                           |
 770                           ---->  DNS server (10.0.2.3)
 771                           |
 772                           ---->  SMB server (10.0.2.4)
 773@end example
 774
 775The QEMU VM behaves as if it was behind a firewall which blocks all
 776incoming connections. You can use a DHCP client to automatically
 777configure the network in the QEMU VM. The DHCP server assign addresses
 778to the hosts starting from 10.0.2.15.
 779
 780In order to check that the user mode network is working, you can ping
 781the address 10.0.2.2 and verify that you got an address in the range
 78210.0.2.x from the QEMU virtual DHCP server.
 783
 784Note that ICMP traffic in general does not work with user mode networking.
 785@code{ping}, aka. ICMP echo, to the local router (10.0.2.2) shall work,
 786however. If you're using QEMU on Linux >= 3.0, it can use unprivileged ICMP
 787ping sockets to allow @code{ping} to the Internet. The host admin has to set
 788the ping_group_range in order to grant access to those sockets. To allow ping
 789for GID 100 (usually users group):
 790
 791@example
 792echo 100 100 > /proc/sys/net/ipv4/ping_group_range
 793@end example
 794
 795When using the built-in TFTP server, the router is also the TFTP
 796server.
 797
 798When using the @option{'-netdev user,hostfwd=...'} option, TCP or UDP
 799connections can be redirected from the host to the guest. It allows for
 800example to redirect X11, telnet or SSH connections.
 801
 802@subsection Hubs
 803
 804QEMU can simulate several hubs. A hub can be thought of as a virtual connection
 805between several network devices. These devices can be for example QEMU virtual
 806ethernet cards or virtual Host ethernet devices (TAP devices). You can connect
 807guest NICs or host network backends to such a hub using the @option{-netdev
 808hubport} or @option{-nic hubport} options. The legacy @option{-net} option
 809also connects the given device to the emulated hub with ID 0 (i.e. the default
 810hub) unless you specify a netdev with @option{-net nic,netdev=xxx} here.
 811
 812@subsection Connecting emulated networks between QEMU instances
 813
 814Using the @option{-netdev socket} (or @option{-nic socket} or
 815@option{-net socket}) option, it is possible to create emulated
 816networks that span several QEMU instances.
 817See the description of the @option{-netdev socket} option in the
 818@ref{sec_invocation,,Invocation chapter} to have a basic example.
 819
 820@node pcsys_other_devs
 821@section Other Devices
 822
 823@subsection Inter-VM Shared Memory device
 824
 825On Linux hosts, a shared memory device is available.  The basic syntax
 826is:
 827
 828@example
 829qemu-system-x86_64 -device ivshmem-plain,memdev=@var{hostmem}
 830@end example
 831
 832where @var{hostmem} names a host memory backend.  For a POSIX shared
 833memory backend, use something like
 834
 835@example
 836-object memory-backend-file,size=1M,share,mem-path=/dev/shm/ivshmem,id=@var{hostmem}
 837@end example
 838
 839If desired, interrupts can be sent between guest VMs accessing the same shared
 840memory region.  Interrupt support requires using a shared memory server and
 841using a chardev socket to connect to it.  The code for the shared memory server
 842is qemu.git/contrib/ivshmem-server.  An example syntax when using the shared
 843memory server is:
 844
 845@example
 846# First start the ivshmem server once and for all
 847ivshmem-server -p @var{pidfile} -S @var{path} -m @var{shm-name} -l @var{shm-size} -n @var{vectors}
 848
 849# Then start your qemu instances with matching arguments
 850qemu-system-x86_64 -device ivshmem-doorbell,vectors=@var{vectors},chardev=@var{id}
 851                 -chardev socket,path=@var{path},id=@var{id}
 852@end example
 853
 854When using the server, the guest will be assigned a VM ID (>=0) that allows guests
 855using the same server to communicate via interrupts.  Guests can read their
 856VM ID from a device register (see ivshmem-spec.txt).
 857
 858@subsubsection Migration with ivshmem
 859
 860With device property @option{master=on}, the guest will copy the shared
 861memory on migration to the destination host.  With @option{master=off},
 862the guest will not be able to migrate with the device attached.  In the
 863latter case, the device should be detached and then reattached after
 864migration using the PCI hotplug support.
 865
 866At most one of the devices sharing the same memory can be master.  The
 867master must complete migration before you plug back the other devices.
 868
 869@subsubsection ivshmem and hugepages
 870
 871Instead of specifying the <shm size> using POSIX shm, you may specify
 872a memory backend that has hugepage support:
 873
 874@example
 875qemu-system-x86_64 -object memory-backend-file,size=1G,mem-path=/dev/hugepages/my-shmem-file,share,id=mb1
 876                 -device ivshmem-plain,memdev=mb1
 877@end example
 878
 879ivshmem-server also supports hugepages mount points with the
 880@option{-m} memory path argument.
 881
 882@node direct_linux_boot
 883@section Direct Linux Boot
 884
 885This section explains how to launch a Linux kernel inside QEMU without
 886having to make a full bootable image. It is very useful for fast Linux
 887kernel testing.
 888
 889The syntax is:
 890@example
 891qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
 892@end example
 893
 894Use @option{-kernel} to provide the Linux kernel image and
 895@option{-append} to give the kernel command line arguments. The
 896@option{-initrd} option can be used to provide an INITRD image.
 897
 898When using the direct Linux boot, a disk image for the first hard disk
 899@file{hda} is required because its boot sector is used to launch the
 900Linux kernel.
 901
 902If you do not need graphical output, you can disable it and redirect
 903the virtual serial port and the QEMU monitor to the console with the
 904@option{-nographic} option. The typical command line is:
 905@example
 906qemu-system-i386 -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
 907                 -append "root=/dev/hda console=ttyS0" -nographic
 908@end example
 909
 910Use @key{Ctrl-a c} to switch between the serial console and the
 911monitor (@pxref{pcsys_keys}).
 912
 913@node pcsys_usb
 914@section USB emulation
 915
 916QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can
 917plug virtual USB devices or real host USB devices (only works with certain
 918host operating systems). QEMU will automatically create and connect virtual
 919USB hubs as necessary to connect multiple USB devices.
 920
 921@menu
 922* usb_devices::
 923* host_usb_devices::
 924@end menu
 925@node usb_devices
 926@subsection Connecting USB devices
 927
 928USB devices can be connected with the @option{-device usb-...} command line
 929option or the @code{device_add} monitor command. Available devices are:
 930
 931@table @code
 932@item usb-mouse
 933Virtual Mouse.  This will override the PS/2 mouse emulation when activated.
 934@item usb-tablet
 935Pointer device that uses absolute coordinates (like a touchscreen).
 936This means QEMU is able to report the mouse position without having
 937to grab the mouse.  Also overrides the PS/2 mouse emulation when activated.
 938@item usb-storage,drive=@var{drive_id}
 939Mass storage device backed by @var{drive_id} (@pxref{disk_images})
 940@item usb-uas
 941USB attached SCSI device, see
 942@url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
 943for details
 944@item usb-bot
 945Bulk-only transport storage device, see
 946@url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt}
 947for details here, too
 948@item usb-mtp,rootdir=@var{dir}
 949Media transfer protocol device, using @var{dir} as root of the file tree
 950that is presented to the guest.
 951@item usb-host,hostbus=@var{bus},hostaddr=@var{addr}
 952Pass through the host device identified by @var{bus} and @var{addr}
 953@item usb-host,vendorid=@var{vendor},productid=@var{product}
 954Pass through the host device identified by @var{vendor} and @var{product} ID
 955@item usb-wacom-tablet
 956Virtual Wacom PenPartner tablet.  This device is similar to the @code{tablet}
 957above but it can be used with the tslib library because in addition to touch
 958coordinates it reports touch pressure.
 959@item usb-kbd
 960Standard USB keyboard.  Will override the PS/2 keyboard (if present).
 961@item usb-serial,chardev=@var{id}
 962Serial converter. This emulates an FTDI FT232BM chip connected to host character
 963device @var{id}.
 964@item usb-braille,chardev=@var{id}
 965Braille device.  This will use BrlAPI to display the braille output on a real
 966or fake device referenced by @var{id}.
 967@item usb-net[,netdev=@var{id}]
 968Network adapter that supports CDC ethernet and RNDIS protocols.  @var{id}
 969specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}.
 970For instance, user-mode networking can be used with
 971@example
 972qemu-system-i386 [...] -netdev user,id=net0 -device usb-net,netdev=net0
 973@end example
 974@item usb-ccid
 975Smartcard reader device
 976@item usb-audio
 977USB audio device
 978@item usb-bt-dongle
 979Bluetooth dongle for the transport layer of HCI. It is connected to HCI
 980scatternet 0 by default (corresponds to @code{-bt hci,vlan=0}).
 981Note that the syntax for the @code{-device usb-bt-dongle} option is not as
 982useful yet as it was with the legacy @code{-usbdevice} option. So to
 983configure an USB bluetooth device, you might need to use
 984"@code{-usbdevice bt}[:@var{hci-type}]" instead. This configures a
 985bluetooth dongle whose type is specified in the same format as with
 986the @option{-bt hci} option, @pxref{bt-hcis,,allowed HCI types}.  If
 987no type is given, the HCI logic corresponds to @code{-bt hci,vlan=0}.
 988This USB device implements the USB Transport Layer of HCI.  Example
 989usage:
 990@example
 991@command{qemu-system-i386} [...@var{OPTIONS}...] @option{-usbdevice} bt:hci,vlan=3 @option{-bt} device:keyboard,vlan=3
 992@end example
 993@end table
 994
 995@node host_usb_devices
 996@subsection Using host USB devices on a Linux host
 997
 998WARNING: this is an experimental feature. QEMU will slow down when
 999using it. USB devices requiring real time streaming (i.e. USB Video
1000Cameras) are not supported yet.
1001
1002@enumerate
1003@item If you use an early Linux 2.4 kernel, verify that no Linux driver
1004is actually using the USB device. A simple way to do that is simply to
1005disable the corresponding kernel module by renaming it from @file{mydriver.o}
1006to @file{mydriver.o.disabled}.
1007
1008@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that:
1009@example
1010ls /proc/bus/usb
1011001  devices  drivers
1012@end example
1013
1014@item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
1015@example
1016chown -R myuid /proc/bus/usb
1017@end example
1018
1019@item Launch QEMU and do in the monitor:
1020@example
1021info usbhost
1022  Device 1.2, speed 480 Mb/s
1023    Class 00: USB device 1234:5678, USB DISK
1024@end example
1025You should see the list of the devices you can use (Never try to use
1026hubs, it won't work).
1027
1028@item Add the device in QEMU by using:
1029@example
1030device_add usb-host,vendorid=0x1234,productid=0x5678
1031@end example
1032
1033Normally the guest OS should report that a new USB device is plugged.
1034You can use the option @option{-device usb-host,...} to do the same.
1035
1036@item Now you can try to use the host USB device in QEMU.
1037
1038@end enumerate
1039
1040When relaunching QEMU, you may have to unplug and plug again the USB
1041device to make it work again (this is a bug).
1042
1043@node vnc_security
1044@section VNC security
1045
1046The VNC server capability provides access to the graphical console
1047of the guest VM across the network. This has a number of security
1048considerations depending on the deployment scenarios.
1049
1050@menu
1051* vnc_sec_none::
1052* vnc_sec_password::
1053* vnc_sec_certificate::
1054* vnc_sec_certificate_verify::
1055* vnc_sec_certificate_pw::
1056* vnc_sec_sasl::
1057* vnc_sec_certificate_sasl::
1058* vnc_setup_sasl::
1059@end menu
1060@node vnc_sec_none
1061@subsection Without passwords
1062
1063The simplest VNC server setup does not include any form of authentication.
1064For this setup it is recommended to restrict it to listen on a UNIX domain
1065socket only. For example
1066
1067@example
1068qemu-system-i386 [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc
1069@end example
1070
1071This ensures that only users on local box with read/write access to that
1072path can access the VNC server. To securely access the VNC server from a
1073remote machine, a combination of netcat+ssh can be used to provide a secure
1074tunnel.
1075
1076@node vnc_sec_password
1077@subsection With passwords
1078
1079The VNC protocol has limited support for password based authentication. Since
1080the protocol limits passwords to 8 characters it should not be considered
1081to provide high security. The password can be fairly easily brute-forced by
1082a client making repeat connections. For this reason, a VNC server using password
1083authentication should be restricted to only listen on the loopback interface
1084or UNIX domain sockets. Password authentication is not supported when operating
1085in FIPS 140-2 compliance mode as it requires the use of the DES cipher. Password
1086authentication is requested with the @code{password} option, and then once QEMU
1087is running the password is set with the monitor. Until the monitor is used to
1088set the password all clients will be rejected.
1089
1090@example
1091qemu-system-i386 [...OPTIONS...] -vnc :1,password -monitor stdio
1092(qemu) change vnc password
1093Password: ********
1094(qemu)
1095@end example
1096
1097@node vnc_sec_certificate
1098@subsection With x509 certificates
1099
1100The QEMU VNC server also implements the VeNCrypt extension allowing use of
1101TLS for encryption of the session, and x509 certificates for authentication.
1102The use of x509 certificates is strongly recommended, because TLS on its
1103own is susceptible to man-in-the-middle attacks. Basic x509 certificate
1104support provides a secure session, but no authentication. This allows any
1105client to connect, and provides an encrypted session.
1106
1107@example
1108qemu-system-i386 [...OPTIONS...] \
1109  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=no \
1110  -vnc :1,tls-creds=tls0 -monitor stdio
1111@end example
1112
1113In the above example @code{/etc/pki/qemu} should contain at least three files,
1114@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged
1115users will want to use a private directory, for example @code{$HOME/.pki/qemu}.
1116NB the @code{server-key.pem} file should be protected with file mode 0600 to
1117only be readable by the user owning it.
1118
1119@node vnc_sec_certificate_verify
1120@subsection With x509 certificates and client verification
1121
1122Certificates can also provide a means to authenticate the client connecting.
1123The server will request that the client provide a certificate, which it will
1124then validate against the CA certificate. This is a good choice if deploying
1125in an environment with a private internal certificate authority. It uses the
1126same syntax as previously, but with @code{verify-peer} set to @code{yes}
1127instead.
1128
1129@example
1130qemu-system-i386 [...OPTIONS...] \
1131  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
1132  -vnc :1,tls-creds=tls0 -monitor stdio
1133@end example
1134
1135
1136@node vnc_sec_certificate_pw
1137@subsection With x509 certificates, client verification and passwords
1138
1139Finally, the previous method can be combined with VNC password authentication
1140to provide two layers of authentication for clients.
1141
1142@example
1143qemu-system-i386 [...OPTIONS...] \
1144  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
1145  -vnc :1,tls-creds=tls0,password -monitor stdio
1146(qemu) change vnc password
1147Password: ********
1148(qemu)
1149@end example
1150
1151
1152@node vnc_sec_sasl
1153@subsection With SASL authentication
1154
1155The SASL authentication method is a VNC extension, that provides an
1156easily extendable, pluggable authentication method. This allows for
1157integration with a wide range of authentication mechanisms, such as
1158PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more.
1159The strength of the authentication depends on the exact mechanism
1160configured. If the chosen mechanism also provides a SSF layer, then
1161it will encrypt the datastream as well.
1162
1163Refer to the later docs on how to choose the exact SASL mechanism
1164used for authentication, but assuming use of one supporting SSF,
1165then QEMU can be launched with:
1166
1167@example
1168qemu-system-i386 [...OPTIONS...] -vnc :1,sasl -monitor stdio
1169@end example
1170
1171@node vnc_sec_certificate_sasl
1172@subsection With x509 certificates and SASL authentication
1173
1174If the desired SASL authentication mechanism does not supported
1175SSF layers, then it is strongly advised to run it in combination
1176with TLS and x509 certificates. This provides securely encrypted
1177data stream, avoiding risk of compromising of the security
1178credentials. This can be enabled, by combining the 'sasl' option
1179with the aforementioned TLS + x509 options:
1180
1181@example
1182qemu-system-i386 [...OPTIONS...] \
1183  -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server,verify-peer=yes \
1184  -vnc :1,tls-creds=tls0,sasl -monitor stdio
1185@end example
1186
1187@node vnc_setup_sasl
1188
1189@subsection Configuring SASL mechanisms
1190
1191The following documentation assumes use of the Cyrus SASL implementation on a
1192Linux host, but the principles should apply to any other SASL implementation
1193or host. When SASL is enabled, the mechanism configuration will be loaded from
1194system default SASL service config /etc/sasl2/qemu.conf. If running QEMU as an
1195unprivileged user, an environment variable SASL_CONF_PATH can be used to make
1196it search alternate locations for the service config file.
1197
1198If the TLS option is enabled for VNC, then it will provide session encryption,
1199otherwise the SASL mechanism will have to provide encryption. In the latter
1200case the list of possible plugins that can be used is drastically reduced. In
1201fact only the GSSAPI SASL mechanism provides an acceptable level of security
1202by modern standards. Previous versions of QEMU referred to the DIGEST-MD5
1203mechanism, however, it has multiple serious flaws described in detail in
1204RFC 6331 and thus should never be used any more. The SCRAM-SHA-1 mechanism
1205provides a simple username/password auth facility similar to DIGEST-MD5, but
1206does not support session encryption, so can only be used in combination with
1207TLS.
1208
1209When not using TLS the recommended configuration is
1210
1211@example
1212mech_list: gssapi
1213keytab: /etc/qemu/krb5.tab
1214@end example
1215
1216This says to use the 'GSSAPI' mechanism with the Kerberos v5 protocol, with
1217the server principal stored in /etc/qemu/krb5.tab. For this to work the
1218administrator of your KDC must generate a Kerberos principal for the server,
1219with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' replacing
1220'somehost.example.com' with the fully qualified host name of the machine
1221running QEMU, and 'EXAMPLE.COM' with the Kerberos Realm.
1222
1223When using TLS, if username+password authentication is desired, then a
1224reasonable configuration is
1225
1226@example
1227mech_list: scram-sha-1
1228sasldb_path: /etc/qemu/passwd.db
1229@end example
1230
1231The @code{saslpasswd2} program can be used to populate the @code{passwd.db}
1232file with accounts.
1233
1234Other SASL configurations will be left as an exercise for the reader. Note that
1235all mechanisms, except GSSAPI, should be combined with use of TLS to ensure a
1236secure data channel.
1237
1238
1239@node network_tls
1240@section TLS setup for network services
1241
1242Almost all network services in QEMU have the ability to use TLS for
1243session data encryption, along with x509 certificates for simple
1244client authentication. What follows is a description of how to
1245generate certificates suitable for usage with QEMU, and applies to
1246the VNC server, character devices with the TCP backend, NBD server
1247and client, and migration server and client.
1248
1249At a high level, QEMU requires certificates and private keys to be
1250provided in PEM format. Aside from the core fields, the certificates
1251should include various extension data sets, including v3 basic
1252constraints data, key purpose, key usage and subject alt name.
1253
1254The GnuTLS package includes a command called @code{certtool} which can
1255be used to easily generate certificates and keys in the required format
1256with expected data present. Alternatively a certificate management
1257service may be used.
1258
1259At a minimum it is necessary to setup a certificate authority, and
1260issue certificates to each server. If using x509 certificates for
1261authentication, then each client will also need to be issued a
1262certificate.
1263
1264Assuming that the QEMU network services will only ever be exposed to
1265clients on a private intranet, there is no need to use a commercial
1266certificate authority to create certificates. A self-signed CA is
1267sufficient, and in fact likely to be more secure since it removes
1268the ability of malicious 3rd parties to trick the CA into mis-issuing
1269certs for impersonating your services. The only likely exception
1270where a commercial CA might be desirable is if enabling the VNC
1271websockets server and exposing it directly to remote browser clients.
1272In such a case it might be useful to use a commercial CA to avoid
1273needing to install custom CA certs in the web browsers.
1274
1275The recommendation is for the server to keep its certificates in either
1276@code{/etc/pki/qemu} or for unprivileged users in @code{$HOME/.pki/qemu}.
1277
1278@menu
1279* tls_generate_ca::
1280* tls_generate_server::
1281* tls_generate_client::
1282* tls_creds_setup::
1283* tls_psk::
1284@end menu
1285@node tls_generate_ca
1286@subsection Setup the Certificate Authority
1287
1288This step only needs to be performed once per organization / organizational
1289unit. First the CA needs a private key. This key must be kept VERY secret
1290and secure. If this key is compromised the entire trust chain of the certificates
1291issued with it is lost.
1292
1293@example
1294# certtool --generate-privkey > ca-key.pem
1295@end example
1296
1297To generate a self-signed certificate requires one core piece of information,
1298the name of the organization. A template file @code{ca.info} should be
1299populated with the desired data to avoid having to deal with interactive
1300prompts from certtool:
1301@example
1302# cat > ca.info <<EOF
1303cn = Name of your organization
1304ca
1305cert_signing_key
1306EOF
1307# certtool --generate-self-signed \
1308           --load-privkey ca-key.pem
1309           --template ca.info \
1310           --outfile ca-cert.pem
1311@end example
1312
1313The @code{ca} keyword in the template sets the v3 basic constraints extension
1314to indicate this certificate is for a CA, while @code{cert_signing_key} sets
1315the key usage extension to indicate this will be used for signing other keys.
1316The generated @code{ca-cert.pem} file should be copied to all servers and
1317clients wishing to utilize TLS support in the VNC server. The @code{ca-key.pem}
1318must not be disclosed/copied anywhere except the host responsible for issuing
1319certificates.
1320
1321@node tls_generate_server
1322@subsection Issuing server certificates
1323
1324Each server (or host) needs to be issued with a key and certificate. When connecting
1325the certificate is sent to the client which validates it against the CA certificate.
1326The core pieces of information for a server certificate are the hostnames and/or IP
1327addresses that will be used by clients when connecting. The hostname / IP address
1328that the client specifies when connecting will be validated against the hostname(s)
1329and IP address(es) recorded in the server certificate, and if no match is found
1330the client will close the connection.
1331
1332Thus it is recommended that the server certificate include both the fully qualified
1333and unqualified hostnames. If the server will have permanently assigned IP address(es),
1334and clients are likely to use them when connecting, they may also be included in the
1335certificate. Both IPv4 and IPv6 addresses are supported. Historically certificates
1336only included 1 hostname in the @code{CN} field, however, usage of this field for
1337validation is now deprecated. Instead modern TLS clients will validate against the
1338Subject Alt Name extension data, which allows for multiple entries. In the future
1339usage of the @code{CN} field may be discontinued entirely, so providing SAN
1340extension data is strongly recommended.
1341
1342On the host holding the CA, create template files containing the information
1343for each server, and use it to issue server certificates.
1344
1345@example
1346# cat > server-hostNNN.info <<EOF
1347organization = Name  of your organization
1348cn = hostNNN.foo.example.com
1349dns_name = hostNNN
1350dns_name = hostNNN.foo.example.com
1351ip_address = 10.0.1.87
1352ip_address = 192.8.0.92
1353ip_address = 2620:0:cafe::87
1354ip_address = 2001:24::92
1355tls_www_server
1356encryption_key
1357signing_key
1358EOF
1359# certtool --generate-privkey > server-hostNNN-key.pem
1360# certtool --generate-certificate \
1361           --load-ca-certificate ca-cert.pem \
1362           --load-ca-privkey ca-key.pem \
1363           --load-privkey server-hostNNN-key.pem \
1364           --template server-hostNNN.info \
1365           --outfile server-hostNNN-cert.pem
1366@end example
1367
1368The @code{dns_name} and @code{ip_address} fields in the template are setting
1369the subject alt name extension data. The @code{tls_www_server} keyword is the
1370key purpose extension to indicate this certificate is intended for usage in
1371a web server. Although QEMU network services are not in fact HTTP servers
1372(except for VNC websockets), setting this key purpose is still recommended.
1373The @code{encryption_key} and @code{signing_key} keyword is the key usage
1374extension to indicate this certificate is intended for usage in the data
1375session.
1376
1377The @code{server-hostNNN-key.pem} and @code{server-hostNNN-cert.pem} files
1378should now be securely copied to the server for which they were generated,
1379and renamed to @code{server-key.pem} and @code{server-cert.pem} when added
1380to the @code{/etc/pki/qemu} directory on the target host. The @code{server-key.pem}
1381file is security sensitive and should be kept protected with file mode 0600
1382to prevent disclosure.
1383
1384@node tls_generate_client
1385@subsection Issuing client certificates
1386
1387The QEMU x509 TLS credential setup defaults to enabling client verification
1388using certificates, providing a simple authentication mechanism. If this
1389default is used, each client also needs to be issued a certificate. The client
1390certificate contains enough metadata to uniquely identify the client with the
1391scope of the certificate authority. The client certificate would typically
1392include fields for organization, state, city, building, etc.
1393
1394Once again on the host holding the CA, create template files containing the
1395information for each client, and use it to issue client certificates.
1396
1397
1398@example
1399# cat > client-hostNNN.info <<EOF
1400country = GB
1401state = London
1402locality = City Of London
1403organization = Name of your organization
1404cn = hostNNN.foo.example.com
1405tls_www_client
1406encryption_key
1407signing_key
1408EOF
1409# certtool --generate-privkey > client-hostNNN-key.pem
1410# certtool --generate-certificate \
1411           --load-ca-certificate ca-cert.pem \
1412           --load-ca-privkey ca-key.pem \
1413           --load-privkey client-hostNNN-key.pem \
1414           --template client-hostNNN.info \
1415           --outfile client-hostNNN-cert.pem
1416@end example
1417
1418The subject alt name extension data is not required for clients, so the
1419the @code{dns_name} and @code{ip_address} fields are not included.
1420The @code{tls_www_client} keyword is the key purpose extension to indicate
1421this certificate is intended for usage in a web client. Although QEMU
1422network clients are not in fact HTTP clients, setting this key purpose is
1423still recommended. The @code{encryption_key} and @code{signing_key} keyword
1424is the key usage extension to indicate this certificate is intended for
1425usage in the data session.
1426
1427The @code{client-hostNNN-key.pem} and @code{client-hostNNN-cert.pem} files
1428should now be securely copied to the client for which they were generated,
1429and renamed to @code{client-key.pem} and @code{client-cert.pem} when added
1430to the @code{/etc/pki/qemu} directory on the target host. The @code{client-key.pem}
1431file is security sensitive and should be kept protected with file mode 0600
1432to prevent disclosure.
1433
1434If a single host is going to be using TLS in both a client and server
1435role, it is possible to create a single certificate to cover both roles.
1436This would be quite common for the migration and NBD services, where a
1437QEMU process will be started by accepting a TLS protected incoming migration,
1438and later itself be migrated out to another host. To generate a single
1439certificate, simply include the template data from both the client and server
1440instructions in one.
1441
1442@example
1443# cat > both-hostNNN.info <<EOF
1444country = GB
1445state = London
1446locality = City Of London
1447organization = Name of your organization
1448cn = hostNNN.foo.example.com
1449dns_name = hostNNN
1450dns_name = hostNNN.foo.example.com
1451ip_address = 10.0.1.87
1452ip_address = 192.8.0.92
1453ip_address = 2620:0:cafe::87
1454ip_address = 2001:24::92
1455tls_www_server
1456tls_www_client
1457encryption_key
1458signing_key
1459EOF
1460# certtool --generate-privkey > both-hostNNN-key.pem
1461# certtool --generate-certificate \
1462           --load-ca-certificate ca-cert.pem \
1463           --load-ca-privkey ca-key.pem \
1464           --load-privkey both-hostNNN-key.pem \
1465           --template both-hostNNN.info \
1466           --outfile both-hostNNN-cert.pem
1467@end example
1468
1469When copying the PEM files to the target host, save them twice,
1470once as @code{server-cert.pem} and @code{server-key.pem}, and
1471again as @code{client-cert.pem} and @code{client-key.pem}.
1472
1473@node tls_creds_setup
1474@subsection TLS x509 credential configuration
1475
1476QEMU has a standard mechanism for loading x509 credentials that will be
1477used for network services and clients. It requires specifying the
1478@code{tls-creds-x509} class name to the @code{--object} command line
1479argument for the system emulators.  Each set of credentials loaded should
1480be given a unique string identifier via the @code{id} parameter. A single
1481set of TLS credentials can be used for multiple network backends, so VNC,
1482migration, NBD, character devices can all share the same credentials. Note,
1483however, that credentials for use in a client endpoint must be loaded
1484separately from those used in a server endpoint.
1485
1486When specifying the object, the @code{dir} parameters specifies which
1487directory contains the credential files. This directory is expected to
1488contain files with the names mentioned previously, @code{ca-cert.pem},
1489@code{server-key.pem}, @code{server-cert.pem}, @code{client-key.pem}
1490and @code{client-cert.pem} as appropriate. It is also possible to
1491include a set of pre-generated Diffie-Hellman (DH) parameters in a file
1492@code{dh-params.pem}, which can be created using the
1493@code{certtool --generate-dh-params} command. If omitted, QEMU will
1494dynamically generate DH parameters when loading the credentials.
1495
1496The @code{endpoint} parameter indicates whether the credentials will
1497be used for a network client or server, and determines which PEM
1498files are loaded.
1499
1500The @code{verify} parameter determines whether x509 certificate
1501validation should be performed. This defaults to enabled, meaning
1502clients will always validate the server hostname against the
1503certificate subject alt name fields and/or CN field. It also
1504means that servers will request that clients provide a certificate
1505and validate them. Verification should never be turned off for
1506client endpoints, however, it may be turned off for server endpoints
1507if an alternative mechanism is used to authenticate clients. For
1508example, the VNC server can use SASL to authenticate clients
1509instead.
1510
1511To load server credentials with client certificate validation
1512enabled
1513
1514@example
1515$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=server
1516@end example
1517
1518while to load client credentials use
1519
1520@example
1521$QEMU -object tls-creds-x509,id=tls0,dir=/etc/pki/qemu,endpoint=client
1522@end example
1523
1524Network services which support TLS will all have a @code{tls-creds}
1525parameter which expects the ID of the TLS credentials object. For
1526example with VNC:
1527
1528@example
1529$QEMU -vnc 0.0.0.0:0,tls-creds=tls0
1530@end example
1531
1532@node tls_psk
1533@subsection TLS Pre-Shared Keys (PSK)
1534
1535Instead of using certificates, you may also use TLS Pre-Shared Keys
1536(TLS-PSK).  This can be simpler to set up than certificates but is
1537less scalable.
1538
1539Use the GnuTLS @code{psktool} program to generate a @code{keys.psk}
1540file containing one or more usernames and random keys:
1541
1542@example
1543mkdir -m 0700 /tmp/keys
1544psktool -u rich -p /tmp/keys/keys.psk
1545@end example
1546
1547TLS-enabled servers such as qemu-nbd can use this directory like so:
1548
1549@example
1550qemu-nbd \
1551  -t -x / \
1552  --object tls-creds-psk,id=tls0,endpoint=server,dir=/tmp/keys \
1553  --tls-creds tls0 \
1554  image.qcow2
1555@end example
1556
1557When connecting from a qemu-based client you must specify the
1558directory containing @code{keys.psk} and an optional @var{username}
1559(defaults to ``qemu''):
1560
1561@example
1562qemu-img info \
1563  --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=rich,endpoint=client \
1564  --image-opts \
1565  file.driver=nbd,file.host=localhost,file.port=10809,file.tls-creds=tls0,file.export=/
1566@end example
1567
1568@node gdb_usage
1569@section GDB usage
1570
1571QEMU has a primitive support to work with gdb, so that you can do
1572'Ctrl-C' while the virtual machine is running and inspect its state.
1573
1574In order to use gdb, launch QEMU with the '-s' option. It will wait for a
1575gdb connection:
1576@example
1577qemu-system-i386 -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img \
1578                    -append "root=/dev/hda"
1579Connected to host network interface: tun0
1580Waiting gdb connection on port 1234
1581@end example
1582
1583Then launch gdb on the 'vmlinux' executable:
1584@example
1585> gdb vmlinux
1586@end example
1587
1588In gdb, connect to QEMU:
1589@example
1590(gdb) target remote localhost:1234
1591@end example
1592
1593Then you can use gdb normally. For example, type 'c' to launch the kernel:
1594@example
1595(gdb) c
1596@end example
1597
1598Here are some useful tips in order to use gdb on system code:
1599
1600@enumerate
1601@item
1602Use @code{info reg} to display all the CPU registers.
1603@item
1604Use @code{x/10i $eip} to display the code at the PC position.
1605@item
1606Use @code{set architecture i8086} to dump 16 bit code. Then use
1607@code{x/10i $cs*16+$eip} to dump the code at the PC position.
1608@end enumerate
1609
1610Advanced debugging options:
1611
1612The default single stepping behavior is step with the IRQs and timer service routines off.  It is set this way because when gdb executes a single step it expects to advance beyond the current instruction.  With the IRQs and timer service routines on, a single step might jump into the one of the interrupt or exception vectors instead of executing the current instruction. This means you may hit the same breakpoint a number of times before executing the instruction gdb wants to have executed.  Because there are rare circumstances where you want to single step into an interrupt vector the behavior can be controlled from GDB.  There are three commands you can query and set the single step behavior:
1613@table @code
1614@item maintenance packet qqemu.sstepbits
1615
1616This will display the MASK bits used to control the single stepping IE:
1617@example
1618(gdb) maintenance packet qqemu.sstepbits
1619sending: "qqemu.sstepbits"
1620received: "ENABLE=1,NOIRQ=2,NOTIMER=4"
1621@end example
1622@item maintenance packet qqemu.sstep
1623
1624This will display the current value of the mask used when single stepping IE:
1625@example
1626(gdb) maintenance packet qqemu.sstep
1627sending: "qqemu.sstep"
1628received: "0x7"
1629@end example
1630@item maintenance packet Qqemu.sstep=HEX_VALUE
1631
1632This will change the single step mask, so if wanted to enable IRQs on the single step, but not timers, you would use:
1633@example
1634(gdb) maintenance packet Qqemu.sstep=0x5
1635sending: "qemu.sstep=0x5"
1636received: "OK"
1637@end example
1638@end table
1639
1640@node pcsys_os_specific
1641@section Target OS specific information
1642
1643@subsection Linux
1644
1645To have access to SVGA graphic modes under X11, use the @code{vesa} or
1646the @code{cirrus} X11 driver. For optimal performances, use 16 bit
1647color depth in the guest and the host OS.
1648
1649When using a 2.6 guest Linux kernel, you should add the option
1650@code{clock=pit} on the kernel command line because the 2.6 Linux
1651kernels make very strict real time clock checks by default that QEMU
1652cannot simulate exactly.
1653
1654When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1655not activated because QEMU is slower with this patch. The QEMU
1656Accelerator Module is also much slower in this case. Earlier Fedora
1657Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporate this
1658patch by default. Newer kernels don't have it.
1659
1660@subsection Windows
1661
1662If you have a slow host, using Windows 95 is better as it gives the
1663best speed. Windows 2000 is also a good choice.
1664
1665@subsubsection SVGA graphic modes support
1666
1667QEMU emulates a Cirrus Logic GD5446 Video
1668card. All Windows versions starting from Windows 95 should recognize
1669and use this graphic card. For optimal performances, use 16 bit color
1670depth in the guest and the host OS.
1671
1672If you are using Windows XP as guest OS and if you want to use high
1673resolution modes which the Cirrus Logic BIOS does not support (i.e. >=
16741280x1024x16), then you should use the VESA VBE virtual graphic card
1675(option @option{-std-vga}).
1676
1677@subsubsection CPU usage reduction
1678
1679Windows 9x does not correctly use the CPU HLT
1680instruction. The result is that it takes host CPU cycles even when
1681idle. You can install the utility from
1682@url{https://web.archive.org/web/20060212132151/http://www.user.cityline.ru/~maxamn/amnhltm.zip}
1683to solve this problem. Note that no such tool is needed for NT, 2000 or XP.
1684
1685@subsubsection Windows 2000 disk full problem
1686
1687Windows 2000 has a bug which gives a disk full problem during its
1688installation. When installing it, use the @option{-win2k-hack} QEMU
1689option to enable a specific workaround. After Windows 2000 is
1690installed, you no longer need this option (this option slows down the
1691IDE transfers).
1692
1693@subsubsection Windows 2000 shutdown
1694
1695Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1696can. It comes from the fact that Windows 2000 does not automatically
1697use the APM driver provided by the BIOS.
1698
1699In order to correct that, do the following (thanks to Struan
1700Bartlett): go to the Control Panel => Add/Remove Hardware & Next =>
1701Add/Troubleshoot a device => Add a new device & Next => No, select the
1702hardware from a list & Next => NT Apm/Legacy Support & Next => Next
1703(again) a few times. Now the driver is installed and Windows 2000 now
1704correctly instructs QEMU to shutdown at the appropriate moment.
1705
1706@subsubsection Share a directory between Unix and Windows
1707
1708See @ref{sec_invocation} about the help of the option
1709@option{'-netdev user,smb=...'}.
1710
1711@subsubsection Windows XP security problem
1712
1713Some releases of Windows XP install correctly but give a security
1714error when booting:
1715@example
1716A problem is preventing Windows from accurately checking the
1717license for this computer. Error code: 0x800703e6.
1718@end example
1719
1720The workaround is to install a service pack for XP after a boot in safe
1721mode. Then reboot, and the problem should go away. Since there is no
1722network while in safe mode, its recommended to download the full
1723installation of SP1 or SP2 and transfer that via an ISO or using the
1724vvfat block device ("-hdb fat:directory_which_holds_the_SP").
1725
1726@subsection MS-DOS and FreeDOS
1727
1728@subsubsection CPU usage reduction
1729
1730DOS does not correctly use the CPU HLT instruction. The result is that
1731it takes host CPU cycles even when idle. You can install the utility from
1732@url{https://web.archive.org/web/20051222085335/http://www.vmware.com/software/dosidle210.zip}
1733to solve this problem.
1734
1735@node QEMU System emulator for non PC targets
1736@chapter QEMU System emulator for non PC targets
1737
1738QEMU is a generic emulator and it emulates many non PC
1739machines. Most of the options are similar to the PC emulator. The
1740differences are mentioned in the following sections.
1741
1742@menu
1743* PowerPC System emulator::
1744* Sparc32 System emulator::
1745* Sparc64 System emulator::
1746* MIPS System emulator::
1747* ARM System emulator::
1748* ColdFire System emulator::
1749* Cris System emulator::
1750* Microblaze System emulator::
1751* SH4 System emulator::
1752* Xtensa System emulator::
1753@end menu
1754
1755@node PowerPC System emulator
1756@section PowerPC System emulator
1757@cindex system emulation (PowerPC)
1758
1759Use the executable @file{qemu-system-ppc} to simulate a complete PREP
1760or PowerMac PowerPC system.
1761
1762QEMU emulates the following PowerMac peripherals:
1763
1764@itemize @minus
1765@item
1766UniNorth or Grackle PCI Bridge
1767@item
1768PCI VGA compatible card with VESA Bochs Extensions
1769@item
17702 PMAC IDE interfaces with hard disk and CD-ROM support
1771@item
1772NE2000 PCI adapters
1773@item
1774Non Volatile RAM
1775@item
1776VIA-CUDA with ADB keyboard and mouse.
1777@end itemize
1778
1779QEMU emulates the following PREP peripherals:
1780
1781@itemize @minus
1782@item
1783PCI Bridge
1784@item
1785PCI VGA compatible card with VESA Bochs Extensions
1786@item
17872 IDE interfaces with hard disk and CD-ROM support
1788@item
1789Floppy disk
1790@item
1791NE2000 network adapters
1792@item
1793Serial port
1794@item
1795PREP Non Volatile RAM
1796@item
1797PC compatible keyboard and mouse.
1798@end itemize
1799
1800QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1801@url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}.
1802
1803Since version 0.9.1, QEMU uses OpenBIOS @url{https://www.openbios.org/}
1804for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL
1805v2) portable firmware implementation. The goal is to implement a 100%
1806IEEE 1275-1994 (referred to as Open Firmware) compliant firmware.
1807
1808@c man begin OPTIONS
1809
1810The following options are specific to the PowerPC emulation:
1811
1812@table @option
1813
1814@item -g @var{W}x@var{H}[x@var{DEPTH}]
1815
1816Set the initial VGA graphic mode. The default is 800x600x32.
1817
1818@item -prom-env @var{string}
1819
1820Set OpenBIOS variables in NVRAM, for example:
1821
1822@example
1823qemu-system-ppc -prom-env 'auto-boot?=false' \
1824 -prom-env 'boot-device=hd:2,\yaboot' \
1825 -prom-env 'boot-args=conf=hd:2,\yaboot.conf'
1826@end example
1827
1828These variables are not used by Open Hack'Ware.
1829
1830@end table
1831
1832@c man end
1833
1834
1835More information is available at
1836@url{http://perso.magic.fr/l_indien/qemu-ppc/}.
1837
1838@node Sparc32 System emulator
1839@section Sparc32 System emulator
1840@cindex system emulation (Sparc32)
1841
1842Use the executable @file{qemu-system-sparc} to simulate the following
1843Sun4m architecture machines:
1844@itemize @minus
1845@item
1846SPARCstation 4
1847@item
1848SPARCstation 5
1849@item
1850SPARCstation 10
1851@item
1852SPARCstation 20
1853@item
1854SPARCserver 600MP
1855@item
1856SPARCstation LX
1857@item
1858SPARCstation Voyager
1859@item
1860SPARCclassic
1861@item
1862SPARCbook
1863@end itemize
1864
1865The emulation is somewhat complete. SMP up to 16 CPUs is supported,
1866but Linux limits the number of usable CPUs to 4.
1867
1868QEMU emulates the following sun4m peripherals:
1869
1870@itemize @minus
1871@item
1872IOMMU
1873@item
1874TCX or cgthree Frame buffer
1875@item
1876Lance (Am7990) Ethernet
1877@item
1878Non Volatile RAM M48T02/M48T08
1879@item
1880Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1881and power/reset logic
1882@item
1883ESP SCSI controller with hard disk and CD-ROM support
1884@item
1885Floppy drive (not on SS-600MP)
1886@item
1887CS4231 sound device (only on SS-5, not working yet)
1888@end itemize
1889
1890The number of peripherals is fixed in the architecture.  Maximum
1891memory size depends on the machine type, for SS-5 it is 256MB and for
1892others 2047MB.
1893
1894Since version 0.8.2, QEMU uses OpenBIOS
1895@url{https://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable
1896firmware implementation. The goal is to implement a 100% IEEE
18971275-1994 (referred to as Open Firmware) compliant firmware.
1898
1899A sample Linux 2.6 series kernel and ram disk image are available on
1900the QEMU web site. There are still issues with NetBSD and OpenBSD, but
1901most kernel versions work. Please note that currently older Solaris kernels
1902don't work probably due to interface issues between OpenBIOS and
1903Solaris.
1904
1905@c man begin OPTIONS
1906
1907The following options are specific to the Sparc32 emulation:
1908
1909@table @option
1910
1911@item -g @var{W}x@var{H}x[x@var{DEPTH}]
1912
1913Set the initial graphics mode. For TCX, the default is 1024x768x8 with the
1914option of 1024x768x24. For cgthree, the default is 1024x768x8 with the option
1915of 1152x900x8 for people who wish to use OBP.
1916
1917@item -prom-env @var{string}
1918
1919Set OpenBIOS variables in NVRAM, for example:
1920
1921@example
1922qemu-system-sparc -prom-env 'auto-boot?=false' \
1923 -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single'
1924@end example
1925
1926@item -M [SS-4|SS-5|SS-10|SS-20|SS-600MP|LX|Voyager|SPARCClassic] [|SPARCbook]
1927
1928Set the emulated machine type. Default is SS-5.
1929
1930@end table
1931
1932@c man end
1933
1934@node Sparc64 System emulator
1935@section Sparc64 System emulator
1936@cindex system emulation (Sparc64)
1937
1938Use the executable @file{qemu-system-sparc64} to simulate a Sun4u
1939(UltraSPARC PC-like machine), Sun4v (T1 PC-like machine), or generic
1940Niagara (T1) machine. The Sun4u emulator is mostly complete, being
1941able to run Linux, NetBSD and OpenBSD in headless (-nographic) mode. The
1942Sun4v emulator is still a work in progress.
1943
1944The Niagara T1 emulator makes use of firmware and OS binaries supplied in the S10image/ directory
1945of the OpenSPARC T1 project @url{http://download.oracle.com/technetwork/systems/opensparc/OpenSPARCT1_Arch.1.5.tar.bz2}
1946and is able to boot the disk.s10hw2 Solaris image.
1947@example
1948qemu-system-sparc64 -M niagara -L /path-to/S10image/ \
1949                    -nographic -m 256 \
1950                    -drive if=pflash,readonly=on,file=/S10image/disk.s10hw2
1951@end example
1952
1953
1954QEMU emulates the following peripherals:
1955
1956@itemize @minus
1957@item
1958UltraSparc IIi APB PCI Bridge
1959@item
1960PCI VGA compatible card with VESA Bochs Extensions
1961@item
1962PS/2 mouse and keyboard
1963@item
1964Non Volatile RAM M48T59
1965@item
1966PC-compatible serial ports
1967@item
19682 PCI IDE interfaces with hard disk and CD-ROM support
1969@item
1970Floppy disk
1971@end itemize
1972
1973@c man begin OPTIONS
1974
1975The following options are specific to the Sparc64 emulation:
1976
1977@table @option
1978
1979@item -prom-env @var{string}
1980
1981Set OpenBIOS variables in NVRAM, for example:
1982
1983@example
1984qemu-system-sparc64 -prom-env 'auto-boot?=false'
1985@end example
1986
1987@item -M [sun4u|sun4v|niagara]
1988
1989Set the emulated machine type. The default is sun4u.
1990
1991@end table
1992
1993@c man end
1994
1995@node MIPS System emulator
1996@section MIPS System emulator
1997@cindex system emulation (MIPS)
1998
1999@menu
2000* nanoMIPS System emulator ::
2001@end menu
2002
2003Four executables cover simulation of 32 and 64-bit MIPS systems in
2004both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel}
2005@file{qemu-system-mips64} and @file{qemu-system-mips64el}.
2006Five different machine types are emulated:
2007
2008@itemize @minus
2009@item
2010A generic ISA PC-like machine "mips"
2011@item
2012The MIPS Malta prototype board "malta"
2013@item
2014An ACER Pica "pica61". This machine needs the 64-bit emulator.
2015@item
2016MIPS emulator pseudo board "mipssim"
2017@item
2018A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator.
2019@end itemize
2020
2021The generic emulation is supported by Debian 'Etch' and is able to
2022install Debian into a virtual disk image. The following devices are
2023emulated:
2024
2025@itemize @minus
2026@item
2027A range of MIPS CPUs, default is the 24Kf
2028@item
2029PC style serial port
2030@item
2031PC style IDE disk
2032@item
2033NE2000 network card
2034@end itemize
2035
2036The Malta emulation supports the following devices:
2037
2038@itemize @minus
2039@item
2040Core board with MIPS 24Kf CPU and Galileo system controller
2041@item
2042PIIX4 PCI/USB/SMbus controller
2043@item
2044The Multi-I/O chip's serial device
2045@item
2046PCI network cards (PCnet32 and others)
2047@item
2048Malta FPGA serial device
2049@item
2050Cirrus (default) or any other PCI VGA graphics card
2051@end itemize
2052
2053The Boston board emulation supports the following devices:
2054
2055@itemize @minus
2056@item
2057Xilinx FPGA, which includes a PCIe root port and an UART
2058@item
2059Intel EG20T PCH connects the I/O peripherals, but only the SATA bus is emulated
2060@end itemize
2061
2062The ACER Pica emulation supports:
2063
2064@itemize @minus
2065@item
2066MIPS R4000 CPU
2067@item
2068PC-style IRQ and DMA controllers
2069@item
2070PC Keyboard
2071@item
2072IDE controller
2073@end itemize
2074
2075The MIPS Magnum R4000 emulation supports:
2076
2077@itemize @minus
2078@item
2079MIPS R4000 CPU
2080@item
2081PC-style IRQ controller
2082@item
2083PC Keyboard
2084@item
2085SCSI controller
2086@item
2087G364 framebuffer
2088@end itemize
2089
2090The Fulong 2E emulation supports:
2091
2092@itemize @minus
2093@item
2094Loongson 2E CPU
2095@item
2096Bonito64 system controller as North Bridge
2097@item
2098VT82C686 chipset as South Bridge
2099@item
2100RTL8139D as a network card chipset
2101@end itemize
2102
2103The mipssim pseudo board emulation provides an environment similar
2104to what the proprietary MIPS emulator uses for running Linux.
2105It supports:
2106
2107@itemize @minus
2108@item
2109A range of MIPS CPUs, default is the 24Kf
2110@item
2111PC style serial port
2112@item
2113MIPSnet network emulation
2114@end itemize
2115
2116@node nanoMIPS System emulator
2117@subsection nanoMIPS System emulator
2118@cindex system emulation (nanoMIPS)
2119
2120Executable @file{qemu-system-mipsel} also covers simulation of
212132-bit nanoMIPS system in little endian mode:
2122
2123@itemize @minus
2124@item
2125nanoMIPS I7200 CPU
2126@end itemize
2127
2128Example of @file{qemu-system-mipsel} usage for nanoMIPS is shown below:
2129
2130Download @code{<disk_image_file>} from @url{https://mipsdistros.mips.com/LinuxDistro/nanomips/buildroot/index.html}.
2131
2132Download @code{<kernel_image_file>} from @url{https://mipsdistros.mips.com/LinuxDistro/nanomips/kernels/v4.15.18-432-gb2eb9a8b07a1-20180627102142/index.html}.
2133
2134Start system emulation of Malta board with nanoMIPS I7200 CPU:
2135@example
2136qemu-system-mipsel -cpu I7200 -kernel @code{<kernel_image_file>} \
2137    -M malta -serial stdio -m @code{<memory_size>} -hda @code{<disk_image_file>} \
2138    -append "mem=256m@@0x0 rw console=ttyS0 vga=cirrus vesa=0x111 root=/dev/sda"
2139@end example
2140
2141
2142@node ARM System emulator
2143@section ARM System emulator
2144@cindex system emulation (ARM)
2145
2146Use the executable @file{qemu-system-arm} to simulate a ARM
2147machine. The ARM Integrator/CP board is emulated with the following
2148devices:
2149
2150@itemize @minus
2151@item
2152ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
2153@item
2154Two PL011 UARTs
2155@item
2156SMC 91c111 Ethernet adapter
2157@item
2158PL110 LCD controller
2159@item
2160PL050 KMI with PS/2 keyboard and mouse.
2161@item
2162PL181 MultiMedia Card Interface with SD card.
2163@end itemize
2164
2165The ARM Versatile baseboard is emulated with the following devices:
2166
2167@itemize @minus
2168@item
2169ARM926E, ARM1136 or Cortex-A8 CPU
2170@item
2171PL190 Vectored Interrupt Controller
2172@item
2173Four PL011 UARTs
2174@item
2175SMC 91c111 Ethernet adapter
2176@item
2177PL110 LCD controller
2178@item
2179PL050 KMI with PS/2 keyboard and mouse.
2180@item
2181PCI host bridge.  Note the emulated PCI bridge only provides access to
2182PCI memory space.  It does not provide access to PCI IO space.
2183This means some devices (eg. ne2k_pci NIC) are not usable, and others
2184(eg. rtl8139 NIC) are only usable when the guest drivers use the memory
2185mapped control registers.
2186@item
2187PCI OHCI USB controller.
2188@item
2189LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices.
2190@item
2191PL181 MultiMedia Card Interface with SD card.
2192@end itemize
2193
2194Several variants of the ARM RealView baseboard are emulated,
2195including the EB, PB-A8 and PBX-A9.  Due to interactions with the
2196bootloader, only certain Linux kernel configurations work out
2197of the box on these boards.
2198
2199Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2200enabled in the kernel, and expect 512M RAM.  Kernels for The PBX-A9 board
2201should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
2202disabled and expect 1024M RAM.
2203
2204The following devices are emulated:
2205
2206@itemize @minus
2207@item
2208ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
2209@item
2210ARM AMBA Generic/Distributed Interrupt Controller
2211@item
2212Four PL011 UARTs
2213@item
2214SMC 91c111 or SMSC LAN9118 Ethernet adapter
2215@item
2216PL110 LCD controller
2217@item
2218PL050 KMI with PS/2 keyboard and mouse
2219@item
2220PCI host bridge
2221@item
2222PCI OHCI USB controller
2223@item
2224LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM devices
2225@item
2226PL181 MultiMedia Card Interface with SD card.
2227@end itemize
2228
2229The XScale-based clamshell PDA models ("Spitz", "Akita", "Borzoi"
2230and "Terrier") emulation includes the following peripherals:
2231
2232@itemize @minus
2233@item
2234Intel PXA270 System-on-chip (ARM V5TE core)
2235@item
2236NAND Flash memory
2237@item
2238IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in "Akita"
2239@item
2240On-chip OHCI USB controller
2241@item
2242On-chip LCD controller
2243@item
2244On-chip Real Time Clock
2245@item
2246TI ADS7846 touchscreen controller on SSP bus
2247@item
2248Maxim MAX1111 analog-digital converter on I@math{^2}C bus
2249@item
2250GPIO-connected keyboard controller and LEDs
2251@item
2252Secure Digital card connected to PXA MMC/SD host
2253@item
2254Three on-chip UARTs
2255@item
2256WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses
2257@end itemize
2258
2259The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the
2260following elements:
2261
2262@itemize @minus
2263@item
2264Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2265@item
2266ROM and RAM memories (ROM firmware image can be loaded with -option-rom)
2267@item
2268On-chip LCD controller
2269@item
2270On-chip Real Time Clock
2271@item
2272TI TSC2102i touchscreen controller / analog-digital converter / Audio
2273CODEC, connected through MicroWire and I@math{^2}S busses
2274@item
2275GPIO-connected matrix keypad
2276@item
2277Secure Digital card connected to OMAP MMC/SD host
2278@item
2279Three on-chip UARTs
2280@end itemize
2281
2282Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 / 48)
2283emulation supports the following elements:
2284
2285@itemize @minus
2286@item
2287Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
2288@item
2289RAM and non-volatile OneNAND Flash memories
2290@item
2291Display connected to EPSON remote framebuffer chip and OMAP on-chip
2292display controller and a LS041y3 MIPI DBI-C controller
2293@item
2294TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen controllers
2295driven through SPI bus
2296@item
2297National Semiconductor LM8323-controlled qwerty keyboard driven
2298through I@math{^2}C bus
2299@item
2300Secure Digital card connected to OMAP MMC/SD host
2301@item
2302Three OMAP on-chip UARTs and on-chip STI debugging console
2303@item
2304A Bluetooth(R) transceiver and HCI connected to an UART
2305@item
2306Mentor Graphics "Inventra" dual-role USB controller embedded in a TI
2307TUSB6010 chip - only USB host mode is supported
2308@item
2309TI TMP105 temperature sensor driven through I@math{^2}C bus
2310@item
2311TI TWL92230C power management companion with an RTC on I@math{^2}C bus
2312@item
2313Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
2314through CBUS
2315@end itemize
2316
2317The Luminary Micro Stellaris LM3S811EVB emulation includes the following
2318devices:
2319
2320@itemize @minus
2321@item
2322Cortex-M3 CPU core.
2323@item
232464k Flash and 8k SRAM.
2325@item
2326Timers, UARTs, ADC and I@math{^2}C interface.
2327@item
2328OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus.
2329@end itemize
2330
2331The Luminary Micro Stellaris LM3S6965EVB emulation includes the following
2332devices:
2333
2334@itemize @minus
2335@item
2336Cortex-M3 CPU core.
2337@item
2338256k Flash and 64k SRAM.
2339@item
2340Timers, UARTs, ADC, I@math{^2}C and SSI interfaces.
2341@item
2342OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI.
2343@end itemize
2344
2345The Freecom MusicPal internet radio emulation includes the following
2346elements:
2347
2348@itemize @minus
2349@item
2350Marvell MV88W8618 ARM core.
2351@item
235232 MB RAM, 256 KB SRAM, 8 MB flash.
2353@item
2354Up to 2 16550 UARTs
2355@item
2356MV88W8xx8 Ethernet controller
2357@item
2358MV88W8618 audio controller, WM8750 CODEC and mixer
2359@item
236012864 display with brightness control
2361@item
23622 buttons, 2 navigation wheels with button function
2363@end itemize
2364
2365The Siemens SX1 models v1 and v2 (default) basic emulation.
2366The emulation includes the following elements:
2367
2368@itemize @minus
2369@item
2370Texas Instruments OMAP310 System-on-chip (ARM 925T core)
2371@item
2372ROM and RAM memories (ROM firmware image can be loaded with -pflash)
2373V1
23741 Flash of 16MB and 1 Flash of 8MB
2375V2
23761 Flash of 32MB
2377@item
2378On-chip LCD controller
2379@item
2380On-chip Real Time Clock
2381@item
2382Secure Digital card connected to OMAP MMC/SD host
2383@item
2384Three on-chip UARTs
2385@end itemize
2386
2387A Linux 2.6 test image is available on the QEMU web site. More
2388information is available in the QEMU mailing-list archive.
2389
2390@c man begin OPTIONS
2391
2392The following options are specific to the ARM emulation:
2393
2394@table @option
2395
2396@item -semihosting
2397Enable semihosting syscall emulation.
2398
2399On ARM this implements the "Angel" interface.
2400
2401Note that this allows guest direct access to the host filesystem,
2402so should only be used with trusted guest OS.
2403
2404@end table
2405
2406@c man end
2407
2408@node ColdFire System emulator
2409@section ColdFire System emulator
2410@cindex system emulation (ColdFire)
2411@cindex system emulation (M68K)
2412
2413Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine.
2414The emulator is able to boot a uClinux kernel.
2415
2416The M5208EVB emulation includes the following devices:
2417
2418@itemize @minus
2419@item
2420MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC).
2421@item
2422Three Two on-chip UARTs.
2423@item
2424Fast Ethernet Controller (FEC)
2425@end itemize
2426
2427The AN5206 emulation includes the following devices:
2428
2429@itemize @minus
2430@item
2431MCF5206 ColdFire V2 Microprocessor.
2432@item
2433Two on-chip UARTs.
2434@end itemize
2435
2436@c man begin OPTIONS
2437
2438The following options are specific to the ColdFire emulation:
2439
2440@table @option
2441
2442@item -semihosting
2443Enable semihosting syscall emulation.
2444
2445On M68K this implements the "ColdFire GDB" interface used by libgloss.
2446
2447Note that this allows guest direct access to the host filesystem,
2448so should only be used with trusted guest OS.
2449
2450@end table
2451
2452@c man end
2453
2454@node Cris System emulator
2455@section Cris System emulator
2456@cindex system emulation (Cris)
2457
2458TODO
2459
2460@node Microblaze System emulator
2461@section Microblaze System emulator
2462@cindex system emulation (Microblaze)
2463
2464TODO
2465
2466@node SH4 System emulator
2467@section SH4 System emulator
2468@cindex system emulation (SH4)
2469
2470TODO
2471
2472@node Xtensa System emulator
2473@section Xtensa System emulator
2474@cindex system emulation (Xtensa)
2475
2476Two executables cover simulation of both Xtensa endian options,
2477@file{qemu-system-xtensa} and @file{qemu-system-xtensaeb}.
2478Two different machine types are emulated:
2479
2480@itemize @minus
2481@item
2482Xtensa emulator pseudo board "sim"
2483@item
2484Avnet LX60/LX110/LX200 board
2485@end itemize
2486
2487The sim pseudo board emulation provides an environment similar
2488to one provided by the proprietary Tensilica ISS.
2489It supports:
2490
2491@itemize @minus
2492@item
2493A range of Xtensa CPUs, default is the DC232B
2494@item
2495Console and filesystem access via semihosting calls
2496@end itemize
2497
2498The Avnet LX60/LX110/LX200 emulation supports:
2499
2500@itemize @minus
2501@item
2502A range of Xtensa CPUs, default is the DC232B
2503@item
250416550 UART
2505@item
2506OpenCores 10/100 Mbps Ethernet MAC
2507@end itemize
2508
2509@c man begin OPTIONS
2510
2511The following options are specific to the Xtensa emulation:
2512
2513@table @option
2514
2515@item -semihosting
2516Enable semihosting syscall emulation.
2517
2518Xtensa semihosting provides basic file IO calls, such as open/read/write/seek/select.
2519Tensilica baremetal libc for ISS and linux platform "sim" use this interface.
2520
2521Note that this allows guest direct access to the host filesystem,
2522so should only be used with trusted guest OS.
2523
2524@end table
2525
2526@c man end
2527
2528@node QEMU Guest Agent
2529@chapter QEMU Guest Agent invocation
2530
2531@include qemu-ga.texi
2532
2533@node QEMU User space emulator
2534@chapter QEMU User space emulator
2535
2536@menu
2537* Supported Operating Systems ::
2538* Features::
2539* Linux User space emulator::
2540* BSD User space emulator ::
2541@end menu
2542
2543@node Supported Operating Systems
2544@section Supported Operating Systems
2545
2546The following OS are supported in user space emulation:
2547
2548@itemize @minus
2549@item
2550Linux (referred as qemu-linux-user)
2551@item
2552BSD (referred as qemu-bsd-user)
2553@end itemize
2554
2555@node Features
2556@section Features
2557
2558QEMU user space emulation has the following notable features:
2559
2560@table @strong
2561@item System call translation:
2562QEMU includes a generic system call translator.  This means that
2563the parameters of the system calls can be converted to fix
2564endianness and 32/64-bit mismatches between hosts and targets.
2565IOCTLs can be converted too.
2566
2567@item POSIX signal handling:
2568QEMU can redirect to the running program all signals coming from
2569the host (such as @code{SIGALRM}), as well as synthesize signals from
2570virtual CPU exceptions (for example @code{SIGFPE} when the program
2571executes a division by zero).
2572
2573QEMU relies on the host kernel to emulate most signal system
2574calls, for example to emulate the signal mask.  On Linux, QEMU
2575supports both normal and real-time signals.
2576
2577@item Threading:
2578On Linux, QEMU can emulate the @code{clone} syscall and create a real
2579host thread (with a separate virtual CPU) for each emulated thread.
2580Note that not all targets currently emulate atomic operations correctly.
2581x86 and ARM use a global lock in order to preserve their semantics.
2582@end table
2583
2584QEMU was conceived so that ultimately it can emulate itself. Although
2585it is not very useful, it is an important test to show the power of the
2586emulator.
2587
2588@node Linux User space emulator
2589@section Linux User space emulator
2590
2591@menu
2592* Quick Start::
2593* Wine launch::
2594* Command line options::
2595* Other binaries::
2596@end menu
2597
2598@node Quick Start
2599@subsection Quick Start
2600
2601In order to launch a Linux process, QEMU needs the process executable
2602itself and all the target (x86) dynamic libraries used by it.
2603
2604@itemize
2605
2606@item On x86, you can just try to launch any process by using the native
2607libraries:
2608
2609@example
2610qemu-i386 -L / /bin/ls
2611@end example
2612
2613@code{-L /} tells that the x86 dynamic linker must be searched with a
2614@file{/} prefix.
2615
2616@item Since QEMU is also a linux process, you can launch QEMU with
2617QEMU (NOTE: you can only do that if you compiled QEMU from the sources):
2618
2619@example
2620qemu-i386 -L / qemu-i386 -L / /bin/ls
2621@end example
2622
2623@item On non x86 CPUs, you need first to download at least an x86 glibc
2624(@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that
2625@code{LD_LIBRARY_PATH} is not set:
2626
2627@example
2628unset LD_LIBRARY_PATH
2629@end example
2630
2631Then you can launch the precompiled @file{ls} x86 executable:
2632
2633@example
2634qemu-i386 tests/i386/ls
2635@end example
2636You can look at @file{scripts/qemu-binfmt-conf.sh} so that
2637QEMU is automatically launched by the Linux kernel when you try to
2638launch x86 executables. It requires the @code{binfmt_misc} module in the
2639Linux kernel.
2640
2641@item The x86 version of QEMU is also included. You can try weird things such as:
2642@example
2643qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 \
2644          /usr/local/qemu-i386/bin/ls-i386
2645@end example
2646
2647@end itemize
2648
2649@node Wine launch
2650@subsection Wine launch
2651
2652@itemize
2653
2654@item Ensure that you have a working QEMU with the x86 glibc
2655distribution (see previous section). In order to verify it, you must be
2656able to do:
2657
2658@example
2659qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2660@end example
2661
2662@item Download the binary x86 Wine install
2663(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page).
2664
2665@item Configure Wine on your account. Look at the provided script
2666@file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous
2667@code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}.
2668
2669@item Then you can try the example @file{putty.exe}:
2670
2671@example
2672qemu-i386 /usr/local/qemu-i386/wine/bin/wine \
2673          /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2674@end example
2675
2676@end itemize
2677
2678@node Command line options
2679@subsection Command line options
2680
2681@example
2682@command{qemu-i386} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-cpu} @var{model}] [@option{-g} @var{port}] [@option{-B} @var{offset}] [@option{-R} @var{size}] @var{program} [@var{arguments}...]
2683@end example
2684
2685@table @option
2686@item -h
2687Print the help
2688@item -L path
2689Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2690@item -s size
2691Set the x86 stack size in bytes (default=524288)
2692@item -cpu model
2693Select CPU model (-cpu help for list and additional feature selection)
2694@item -E @var{var}=@var{value}
2695Set environment @var{var} to @var{value}.
2696@item -U @var{var}
2697Remove @var{var} from the environment.
2698@item -B offset
2699Offset guest address by the specified number of bytes.  This is useful when
2700the address region required by guest applications is reserved on the host.
2701This option is currently only supported on some hosts.
2702@item -R size
2703Pre-allocate a guest virtual address space of the given size (in bytes).
2704"G", "M", and "k" suffixes may be used when specifying the size.
2705@end table
2706
2707Debug options:
2708
2709@table @option
2710@item -d item1,...
2711Activate logging of the specified items (use '-d help' for a list of log items)
2712@item -p pagesize
2713Act as if the host page size was 'pagesize' bytes
2714@item -g port
2715Wait gdb connection to port
2716@item -singlestep
2717Run the emulation in single step mode.
2718@end table
2719
2720Environment variables:
2721
2722@table @env
2723@item QEMU_STRACE
2724Print system calls and arguments similar to the 'strace' program
2725(NOTE: the actual 'strace' program will not work because the user
2726space emulator hasn't implemented ptrace).  At the moment this is
2727incomplete.  All system calls that don't have a specific argument
2728format are printed with information for six arguments.  Many
2729flag-style arguments don't have decoders and will show up as numbers.
2730@end table
2731
2732@node Other binaries
2733@subsection Other binaries
2734
2735@cindex user mode (Alpha)
2736@command{qemu-alpha} TODO.
2737
2738@cindex user mode (ARM)
2739@command{qemu-armeb} TODO.
2740
2741@cindex user mode (ARM)
2742@command{qemu-arm} is also capable of running ARM "Angel" semihosted ELF
2743binaries (as implemented by the arm-elf and arm-eabi Newlib/GDB
2744configurations), and arm-uclinux bFLT format binaries.
2745
2746@cindex user mode (ColdFire)
2747@cindex user mode (M68K)
2748@command{qemu-m68k} is capable of running semihosted binaries using the BDM
2749(m5xxx-ram-hosted.ld) or m68k-sim (sim.ld) syscall interfaces, and
2750coldfire uClinux bFLT format binaries.
2751
2752The binary format is detected automatically.
2753
2754@cindex user mode (Cris)
2755@command{qemu-cris} TODO.
2756
2757@cindex user mode (i386)
2758@command{qemu-i386} TODO.
2759@command{qemu-x86_64} TODO.
2760
2761@cindex user mode (Microblaze)
2762@command{qemu-microblaze} TODO.
2763
2764@cindex user mode (MIPS)
2765@command{qemu-mips} executes 32-bit big endian MIPS binaries (MIPS O32 ABI).
2766
2767@command{qemu-mipsel} executes 32-bit little endian MIPS binaries (MIPS O32 ABI).
2768
2769@command{qemu-mips64} executes 64-bit big endian MIPS binaries (MIPS N64 ABI).
2770
2771@command{qemu-mips64el} executes 64-bit little endian MIPS binaries (MIPS N64 ABI).
2772
2773@command{qemu-mipsn32} executes 32-bit big endian MIPS binaries (MIPS N32 ABI).
2774
2775@command{qemu-mipsn32el} executes 32-bit little endian MIPS binaries (MIPS N32 ABI).
2776
2777@cindex user mode (NiosII)
2778@command{qemu-nios2} TODO.
2779
2780@cindex user mode (PowerPC)
2781@command{qemu-ppc64abi32} TODO.
2782@command{qemu-ppc64} TODO.
2783@command{qemu-ppc} TODO.
2784
2785@cindex user mode (SH4)
2786@command{qemu-sh4eb} TODO.
2787@command{qemu-sh4} TODO.
2788
2789@cindex user mode (SPARC)
2790@command{qemu-sparc} can execute Sparc32 binaries (Sparc32 CPU, 32 bit ABI).
2791
2792@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries
2793(Sparc64 CPU, 32 bit ABI).
2794
2795@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and
2796SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI).
2797
2798@node BSD User space emulator
2799@section BSD User space emulator
2800
2801@menu
2802* BSD Status::
2803* BSD Quick Start::
2804* BSD Command line options::
2805@end menu
2806
2807@node BSD Status
2808@subsection BSD Status
2809
2810@itemize @minus
2811@item
2812target Sparc64 on Sparc64: Some trivial programs work.
2813@end itemize
2814
2815@node BSD Quick Start
2816@subsection Quick Start
2817
2818In order to launch a BSD process, QEMU needs the process executable
2819itself and all the target dynamic libraries used by it.
2820
2821@itemize
2822
2823@item On Sparc64, you can just try to launch any process by using the native
2824libraries:
2825
2826@example
2827qemu-sparc64 /bin/ls
2828@end example
2829
2830@end itemize
2831
2832@node BSD Command line options
2833@subsection Command line options
2834
2835@example
2836@command{qemu-sparc64} [@option{-h]} [@option{-d]} [@option{-L} @var{path}] [@option{-s} @var{size}] [@option{-bsd} @var{type}] @var{program} [@var{arguments}...]
2837@end example
2838
2839@table @option
2840@item -h
2841Print the help
2842@item -L path
2843Set the library root path (default=/)
2844@item -s size
2845Set the stack size in bytes (default=524288)
2846@item -ignore-environment
2847Start with an empty environment. Without this option,
2848the initial environment is a copy of the caller's environment.
2849@item -E @var{var}=@var{value}
2850Set environment @var{var} to @var{value}.
2851@item -U @var{var}
2852Remove @var{var} from the environment.
2853@item -bsd type
2854Set the type of the emulated BSD Operating system. Valid values are
2855FreeBSD, NetBSD and OpenBSD (default).
2856@end table
2857
2858Debug options:
2859
2860@table @option
2861@item -d item1,...
2862Activate logging of the specified items (use '-d help' for a list of log items)
2863@item -p pagesize
2864Act as if the host page size was 'pagesize' bytes
2865@item -singlestep
2866Run the emulation in single step mode.
2867@end table
2868
2869@node System requirements
2870@chapter System requirements
2871
2872@section KVM kernel module
2873
2874On x86_64 hosts, the default set of CPU features enabled by the KVM accelerator
2875require the host to be running Linux v4.5 or newer.
2876
2877The OpteronG[345] CPU models require KVM support for RDTSCP, which was
2878added with Linux 4.5 which is supported by the major distros. And even
2879if RHEL7 has kernel 3.10, KVM there has the required functionality there
2880to make it close to a 4.5 or newer kernel.
2881
2882@include docs/security.texi
2883
2884@include qemu-tech.texi
2885
2886@include qemu-deprecated.texi
2887
2888@node Supported build platforms
2889@appendix Supported build platforms
2890
2891QEMU aims to support building and executing on multiple host OS platforms.
2892This appendix outlines which platforms are the major build targets. These
2893platforms are used as the basis for deciding upon the minimum required
2894versions of 3rd party software QEMU depends on. The supported platforms
2895are the targets for automated testing performed by the project when patches
2896are submitted for review, and tested before and after merge.
2897
2898If a platform is not listed here, it does not imply that QEMU won't work.
2899If an unlisted platform has comparable software versions to a listed platform,
2900there is every expectation that it will work. Bug reports are welcome for
2901problems encountered on unlisted platforms unless they are clearly older
2902vintage than what is described here.
2903
2904Note that when considering software versions shipped in distros as support
2905targets, QEMU considers only the version number, and assumes the features in
2906that distro match the upstream release with the same version. In other words,
2907if a distro backports extra features to the software in their distro, QEMU
2908upstream code will not add explicit support for those backports, unless the
2909feature is auto-detectable in a manner that works for the upstream releases
2910too.
2911
2912The Repology site @url{https://repology.org} is a useful resource to identify
2913currently shipped versions of software in various operating systems, though
2914it does not cover all distros listed below.
2915
2916@section Linux OS
2917
2918For distributions with frequent, short-lifetime releases, the project will
2919aim to support all versions that are not end of life by their respective
2920vendors. For the purposes of identifying supported software versions, the
2921project will look at Fedora, Ubuntu, and openSUSE distros. Other short-
2922lifetime distros will be assumed to ship similar software versions.
2923
2924For distributions with long-lifetime releases, the project will aim to support
2925the most recent major version at all times. Support for the previous major
2926version will be dropped 2 years after the new major version is released. For
2927the purposes of identifying supported software versions, the project will look
2928at RHEL, Debian, Ubuntu LTS, and SLES distros. Other long-lifetime distros will
2929be assumed to ship similar software versions.
2930
2931@section Windows
2932
2933The project supports building with current versions of the MinGW toolchain,
2934hosted on Linux.
2935
2936@section macOS
2937
2938The project supports building with the two most recent versions of macOS, with
2939the current homebrew package set available.
2940
2941@section FreeBSD
2942
2943The project aims to support the all the versions which are not end of life.
2944
2945@section NetBSD
2946
2947The project aims to support the most recent major version at all times. Support
2948for the previous major version will be dropped 2 years after the new major
2949version is released.
2950
2951@section OpenBSD
2952
2953The project aims to support the all the versions which are not end of life.
2954
2955@node License
2956@appendix License
2957
2958QEMU is a trademark of Fabrice Bellard.
2959
2960QEMU is released under the
2961@url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
2962version 2. Parts of QEMU have specific licenses, see file
2963@url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
2964
2965@node Index
2966@appendix Index
2967@menu
2968* Concept Index::
2969* Function Index::
2970* Keystroke Index::
2971* Program Index::
2972* Data Type Index::
2973* Variable Index::
2974@end menu
2975
2976@node Concept Index
2977@section Concept Index
2978This is the main index. Should we combine all keywords in one index? TODO
2979@printindex cp
2980
2981@node Function Index
2982@section Function Index
2983This index could be used for command line options and monitor functions.
2984@printindex fn
2985
2986@node Keystroke Index
2987@section Keystroke Index
2988
2989This is a list of all keystrokes which have a special function
2990in system emulation.
2991
2992@printindex ky
2993
2994@node Program Index
2995@section Program Index
2996@printindex pg
2997
2998@node Data Type Index
2999@section Data Type Index
3000
3001This index could be used for qdev device names and options.
3002
3003@printindex tp
3004
3005@node Variable Index
3006@section Variable Index
3007@printindex vr
3008
3009@bye
3010