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