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