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