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