NAME
qemu-doc - QEMU Emulator User Documentation
SYNOPSIS
usage: qemu-system-i386 [options] [disk_image]
DEscRIPTION
The QEMU PC System emulator simulates the following peripherals:
- i440FX host PCI bridge and PIIX3 PCI to ISA bridge
- Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA extensions (hardware level, including all non standard modes).
- PS/2 mouse and keyboard
- 2 PCI IDE interfaces with hard disk and CD-ROM support
- Floppy disk
- PCI and ISA network adapters
- Serial ports
- Creative SoundBlaster 16 sound card
- ENSONIQ AudioPCI ES1370 sound card
- Intel 82801AA AC97 Audio compatible sound card
- Intel HD Audio Controller and HDA codec
- Adlib (OPL2) - Yamaha YM3812 compatible chip
- Gravis Ultrasound GF1 sound card
- CS4231A compatible sound card
- PCI UHCI USB controller and a virtual USB hub.
SMP is supported with up to 255 CPUs.
QEMU uses the PC BIOS from the Seabios project and the Plex86/Bochs LGPL VGA BIOS.
QEMU uses YM3812 emulation by Tatsuyuki Satoh.
QEMU uses GUS emulation (GUSEMU32 <http://www.deinmeister.de/gusemu/>) by Tibor "TS" Schutz.
Note that, by default, GUS shares IRQ(7) with parallel ports and so QEMU must be told to not have parallel ports to have working GUS.
qemu-system-i386 dos.img -soundhw gus -parallel none
Alternatively:
qemu-system-i386 dos.img -device gus,irq=5
Or some other unclaimed IRQ.
CS4231A is the chip used in Windows Sound System and GUSMAX products
OPTIONS
disk_image is a raw hard disk image for IDE hard disk 0. Some targets do not need a disk image.
Standard options:
-h Display help and exit
-version
Display version information and exit
-machine [type=]name[,prop=value[,...]]
Select the emulated machine by name. Use "-machine help" to list available machines. Supported machine properties are:
accel=accels1[:accels2[:...]]
This is used to enable an accelerator. Depending on the target architecture, kvm, xen, or tcg can be available. By default, tcg is used. If there is more than one accelerator
specified, the next one is used if the previous one fails to initialize.
kernel_irqchip=on|off
Enables in-kernel irqchip support for the chosen accelerator when available.
kvm_shadow_mem=size
Defines the size of the KVM shadow MMU.
dump-guest-core=on|off
Include guest memory in a core dump. The default is on.
mem-merge=on|off
Enables or disables memory merge support. This feature, when supported by the host, de-duplicates identical memory pages among VMs instances (enabled by default).
-cpu model
Select CPU model ("-cpu help" for list and additional feature selection)
-smp [cpus=]n[,cores=cores][,threads=threads][,sockets=sockets][,maxcpus=maxcpus]
Simulate an SMP system with n CPUs. On the PC target, up to 255 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs to 4. For the PC target, the number of
cores per socket, the number of threads per cores and the total number of sockets can be specified. Missing values will be computed. If any on the three values is given, the total
number of CPUs n can be omitted. maxcpus specifies the maximum number of hotpluggable CPUs.
-numa opts
Simulate a multi node NUMA system. If mem and cpus are omitted, resources are split equally.
-add-fd fd=fd,set=set[,opaque=opaque]
Add a file descriptor to an fd set. Valid options are:
fd=fd
This option defines the file descriptor of which a duplicate is added to fd set. The file descriptor cannot be stdin, stdout, or stderr.
set=set
This option defines the ID of the fd set to add the file descriptor to.
opaque=opaque
This option defines a free-form string that can be used to describe fd.
You can open an image using pre-opened file descriptors from an fd set:
qemu-system-i386
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
-drive file=/dev/fdset/2,index=0,media=disk
-set group.id.arg=value
Set parameter arg for item id of type group\n"
-global driver.prop=value
Set default value of driver's property prop to value, e.g.:
qemu-system-i386 -global ide-drive.physical_block_size=4096 -drive file=file,if=ide,index=0,media=disk
In particular, you can use this to set driver properties for devices which are created automatically by the machine model. To create a device which is not created automatically and set
properties on it, use -device.
-boot [order=drives][,once=drives][,menu=on|off][,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_timeout][,strict=on|off]
Specify boot order drives as a string of drive letters. Valid drive letters depend on the target achitecture. The x86 PC uses: a, b (floppy 1 and 2), c (first hard disk), d (first CD-
ROM), n-p (Etherboot from network adapter 1-4), hard disk boot is the default. To apply a particular boot order only on the first startup, specify it via once.
Interactive boot menus/prompts can be enabled via menu=on as far as firmware/BIOS supports them. The default is non-interactive boot.
A splash picture could be passed to bios, enabling user to show it as logo, when option splash=sp_name is given and menu=on, If firmware/BIOS supports them. Currently Seabios for X86
system support it. limitation: The splash file could be a jpeg file or a BMP file in 24 BPP format(true color). The resolution should be supported by the SVGA mode, so the recommended
is 320x240, 640x480, 800x640.
A timeout could be passed to bios, guest will pause for rb_timeout ms when boot failed, then reboot. If rb_timeout is '-1', guest will not reboot, qemu passes '-1' to bios by default.
Currently Seabios for X86 system support it.
Do strict boot via strict=on as far as firmware/BIOS supports it. This only effects when boot priority is changed by bootindex options. The default is non-strict boot.
# try to boot from network first, then from hard disk
qemu-system-i386 -boot order=nc
# boot from CD-ROM first, switch back to default order after reboot
qemu-system-i386 -boot once=d
# boot with a splash picture for 5 seconds.
qemu-system-i386 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
Note: The legacy format '-boot drives' is still supported but its use is discouraged as it may be removed from future versions.
-m megs
Set virtual RAM size to megs megabytes. Default is 128 MiB. Optionally, a suffix of "M" or "G" can be used to signify a value in megabytes or gigabytes respectively.
-mem-path path
Allocate guest RAM from a temporarily created file in path.
-mem-prealloc
Preallocate memory when using -mem-path.
-k language
Use keyboard layout language (for example "fr" for French). This option is only needed where it is not easy to get raw PC keycodes (e.g. on Macs, with some X11 servers or with a VNC
display). You don't normally need to use it on PC/Linux or PC/Windows hosts.
The available layouts are:
ar de-ch es fo fr-ca hu ja mk no pt-br sv
da en-gb et fr fr-ch is lt nl pl ru th
de en-us fi fr-be hr it lv nl-be pt sl tr
The default is "en-us".
-audio-help
Will show the audio subsystem help: list of drivers, tunable parameters.
-soundhw card1[,card2,...] or -soundhw all
Enable audio and selected sound hardware. Use 'help' to print all available sound hardware.
qemu-system-i386 -soundhw sb16,adlib disk.img
qemu-system-i386 -soundhw es1370 disk.img
qemu-system-i386 -soundhw ac97 disk.img
qemu-system-i386 -soundhw hda disk.img
qemu-system-i386 -soundhw all disk.img
qemu-system-i386 -soundhw help
Note that Linux's i810_audio OSS kernel (for AC97) module might require manually specifying clocking.
modprobe i810_audio clocking=48000
-balloon none
Disable balloon device.
-balloon virtio[,addr=addr]
Enable virtio balloon device (default), optionally with PCI address addr.
-device driver[,prop[=value][,...]]
Add device driver. prop=value sets driver properties. Valid properties depend on the driver. To get help on possible drivers and properties, use "-device help" and "-device
driver,help".
-name name
Sets the name of the guest. This name will be displayed in the SDL window caption. The name will also be used for the VNC server. Also optionally set the top visible process name in
Linux.
-uuid uuid
Set system UUID.
Block device options:
-fda file
-fdb file
Use file as floppy disk 0/1 image. You can use the host floppy by using /dev/fd0 as filename.
-hda file
-hdb file
-hdc file
-hdd file
Use file as hard disk 0, 1, 2 or 3 image.
-cdrom file
Use file as CD-ROM image (you cannot use -hdc and -cdrom at the same time). You can use the host CD-ROM by using /dev/cdrom as filename.
-drive option[,option[,option[,...]]]
Define a new drive. Valid options are:
file=file
This option defines which disk image to use with this drive. If the filename contains comma, you must double it (for instance, "file=my,,file" to use file "my,file").
Special files such as iSCSI devices can be specified using protocol specific URLs. See the section for "Device URL Syntax" for more information.
if=interface
This option defines on which type on interface the drive is connected. Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio.
bus=bus,unit=unit
These options define where is connected the drive by defining the bus number and the unit id.
index=index
This option defines where is connected the drive by using an index in the list of available connectors of a given interface type.
media=media
This option defines the type of the media: disk or cdrom.
cyls=c,heads=h,secs=s[,trans=t]
These options have the same definition as they have in -hdachs.
snapshot=snapshot
snapshot is "on" or "off" and allows to enable snapshot for given drive (see -snapshot).
cache=cache
cache is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data.
aio=aio
aio is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO.
discard=discard
discard is one of "ignore" (or "off") or "unmap" (or "on") and controls whether discard (also known as trim or unmap) requests are ignored or passed to the filesystem. Some
machine types may not support discard requests.
format=format
Specify which disk format will be used rather than detecting the format. Can be used to specifiy format=raw to avoid interpreting an untrusted format header.
serial=serial
This option specifies the serial number to assign to the device.
addr=addr
Specify the controller's PCI address (if=virtio only).
werror=action,rerror=action
Specify which action to take on write and read errors. Valid actions are: "ignore" (ignore the error and try to continue), "stop" (pause QEMU), "report" (report the error to the
guest), "enospc" (pause QEMU only if the host disk is full; report the error to the guest otherwise). The default setting is werror=enospc and rerror=report.
readonly
Open drive file as read-only. Guest write attempts will fail.
copy-on-read=copy-on-read
copy-on-read is "on" or "off" and enables whether to copy read backing file sectors into the image file.
By default, the cache=writeback mode is used. It will report data writes as completed as soon as the data is present in the host page cache. This is safe as long as your guest OS
makes sure to correctly flush disk caches where needed. If your guest OS does not handle volatile disk write caches correctly and your host crashes or loses power, then the guest may
experience data corruption.
For such guests, you should consider using cache=writethrough. This means that the host page cache will be used to read and write data, but write notification will be sent to the guest
only after QEMU has made sure to flush each write to the disk. Be aware that this has a major impact on performance.
The host page cache can be avoided entirely with cache=none. This will attempt to do disk IO directly to the guest's memory. QEMU may still perform an internal copy of the data. Note
that this is considered a writeback mode and the guest OS must handle the disk write cache correctly in order to avoid data corruption on host crashes.
The host page cache can be avoided while only sending write notifications to the guest when the data has been flushed to the disk using cache=directsync.
In case you don't care about data integrity over host failures, use cache=unsafe. This option tells QEMU that it never needs to write any data to the disk but can instead keep things
in cache. If anything goes wrong, like your host losing power, the disk storage getting disconnected accidentally, etc. your image will most probably be rendered unusable. When using
the -snapshot option, unsafe caching is always used.
Copy-on-read avoids accessing the same backing file sectors repeatedly and is useful when the backing file is over a slow network. By default copy-on-read is off.
Instead of -cdrom you can use:
qemu-system-i386 -drive file=file,index=2,media=cdrom
Instead of -hda, -hdb, -hdc, -hdd, you can use:
qemu-system-i386 -drive file=file,index=0,media=disk
qemu-system-i386 -drive file=file,index=1,media=disk
qemu-system-i386 -drive file=file,index=2,media=disk
qemu-system-i386 -drive file=file,index=3,media=disk
You can open an image using pre-opened file descriptors from an fd set:
qemu-system-i386
-add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
-add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
-drive file=/dev/fdset/2,index=0,media=disk
You can connect a CDROM to the slave of ide0:
qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom
If you don't specify the "file=" argument, you define an empty drive:
qemu-system-i386 -drive if=ide,index=1,media=cdrom
You can connect a SCSI disk with unit ID 6 on the bus #0:
qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6
Instead of -fda, -fdb, you can use:
qemu-system-i386 -drive file=file,index=0,if=floppy
qemu-system-i386 -drive file=file,index=1,if=floppy
By default, interface is "ide" and index is automatically incremented:
qemu-system-i386 -drive file=a -drive file=b"
is interpreted like:
qemu-system-i386 -hda a -hdb b
-mtdblock file
Use file as on-board Flash memory image.
-sd file
Use file as SecureDigital card image.
-pflash file
Use file as a parallel flash image.
-snapshot
Write to temporary files instead of disk image files. In this case, the raw disk image you use is not written back. You can however force the write back by pressing C-a s.
-hdachs c,h,s,[,t]
Force hard disk 0 physical geometry (1 <= c <= 16383, 1 <= h <= 16, 1 <= s <= 63) and optionally force the BIOS translation mode (t=none, lba or auto). Usually QEMU can guess all those
parameters. This option is useful for old MS-DOS disk images.
-fsdev fsdriver,id=id,path=path,[security_model=security_model][,writeout=writeout][,readonly][,socket=socket|sock_fd=sock_fd]
Define a new file system device. Valid options are:
fsdriver
This option specifies the fs driver backend to use. Currently "local", "handle" and "proxy" file system drivers are supported.
id=id
Specifies identifier for this device
path=path
Specifies the export path for the file system device. Files under this path will be available to the 9p client on the guest.
security_model=security_model
Specifies the security model to be used for this export path. Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". In "passthrough" security
model, files are stored using the same credentials as they are created on the guest. This requires QEMU to run as root. In "mapped-xattr" security model, some of the file
attributes like uid, gid, mode bits and link target are stored as file attributes. For "mapped-file" these attributes are stored in the hidden .virtfs_metadata directory.
Directories exported by this security model cannot interact with other unix tools. "none" security model is same as passthrough except the sever won't report failures if it fails
to set file attributes like ownership. Security model is mandatory only for local fsdriver. Other fsdrivers (like handle, proxy) don't take security model as a parameter.
writeout=writeout
This is an optional argument. The only supported value is "immediate". This means that host page cache will be used to read and write data but write notification will be sent to
the guest only when the data has been reported as written by the storage subsystem.
readonly
Enables exporting 9p share as a readonly mount for guests. By default read-write access is given.
socket=socket
Enables proxy filesystem driver to use passed socket file for communicating with virtfs-proxy-helper
sock_fd=sock_fd
Enables proxy filesystem driver to use passed socket descriptor for communicating with virtfs-proxy-helper. Usually a helper like libvirt will create socketpair and pass one of the
fds as sock_fd
-fsdev option is used along with -device driver "virtio-9p-pci".
-device virtio-9p-pci,fsdev=id,mount_tag=mount_tag
Options for virtio-9p-pci driver are:
fsdev=id
Specifies the id value specified along with -fsdev option
mount_tag=mount_tag
Specifies the tag name to be used by the guest to mount this export point
-virtfs fsdriver[,path=path],mount_tag=mount_tag[,security_model=security_model][,writeout=writeout][,readonly][,socket=socket|sock_fd=sock_fd]
The general form of a Virtual File system pass-through options are:
fsdriver
This option specifies the fs driver backend to use. Currently "local", "handle" and "proxy" file system drivers are supported.
id=id
Specifies identifier for this device
path=path
Specifies the export path for the file system device. Files under this path will be available to the 9p client on the guest.
security_model=security_model
Specifies the security model to be used for this export path. Supported security models are "passthrough", "mapped-xattr", "mapped-file" and "none". In "passthrough" security
model, files are stored using the same credentials as they are created on the guest. This requires QEMU to run as root. In "mapped-xattr" security model, some of the file
attributes like uid, gid, mode bits and link target are stored as file attributes. For "mapped-file" these attributes are stored in the hidden .virtfs_metadata directory.
Directories exported by this security model cannot interact with other unix tools. "none" security model is same as passthrough except the sever won't report failures if it fails
to set file attributes like ownership. Security model is mandatory only for local fsdriver. Other fsdrivers (like handle, proxy) don't take security model as a parameter.
writeout=writeout
This is an optional argument. The only supported value is "immediate". This means that host page cache will be used to read and write data but write notification will be sent to
the guest only when the data has been reported as written by the storage subsystem.
readonly
Enables exporting 9p share as a readonly mount for guests. By default read-write access is given.
socket=socket
Enables proxy filesystem driver to use passed socket file for communicating with virtfs-proxy-helper. Usually a helper like libvirt will create socketpair and pass one of the fds
as sock_fd
sock_fd
Enables proxy filesystem driver to use passed 'sock_fd' as the socket descriptor for interfacing with virtfs-proxy-helper
-virtfs_synth
Create synthetic file system image
USB options:
-usb
Enable the USB driver (will be the default soon)
-usbdevice devname
Add the USB device devname.
mouse
Virtual Mouse. This will override the PS/2 mouse emulation when activated.
tablet
Pointer device that uses absolute coordinates (like a touchscreen). This means QEMU is able to report the mouse position without having to grab the mouse. Also overrides the PS/2
mouse emulation when activated.
disk:[format=format]:file
Mass storage device based on file. The optional format argument will be used rather than detecting the format. Can be used to specifiy "format=raw" to avoid interpreting an
untrusted format header.
host:bus.addr
Pass through the host device identified by bus.addr (Linux only).
host:vendor_id:product_id
Pass through the host device identified by vendor_id
