X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;f=qemu-options.hx;h=5dc8b75cdbd4a5357bfe0b48f841a6a060a184fe;hb=8b7acc79b9adb4dda6cc867b90e3a1e873f4f7e8;hp=ce9602fec793f48fd4e8c474b7592862141ebc6b;hpb=f037809907bcc51295a471ad66b14e90f22d8caa;p=qemu.git diff --git a/qemu-options.hx b/qemu-options.hx index ce9602fec..5dc8b75cd 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -73,7 +73,7 @@ Select CPU model (@code{-cpu help} for list and additional feature selection) ETEXI DEF("smp", HAS_ARG, QEMU_OPTION_smp, - "-smp n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" + "-smp [cpus=]n[,maxcpus=cpus][,cores=cores][,threads=threads][,sockets=sockets]\n" " set the number of CPUs to 'n' [default=1]\n" " maxcpus= maximum number of total cpus, including\n" " offline CPUs for hotplug, etc\n" @@ -82,7 +82,7 @@ DEF("smp", HAS_ARG, QEMU_OPTION_smp, " sockets= number of discrete sockets in the system\n", QEMU_ARCH_ALL) STEXI -@item -smp @var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] +@item -smp [cpus=]@var{n}[,cores=@var{cores}][,threads=@var{threads}][,sockets=@var{sockets}][,maxcpus=@var{maxcpus}] @findex -smp Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 CPUs are supported. On Sparc32 target, Linux limits the number of usable CPUs @@ -103,196 +103,6 @@ Simulate a multi node NUMA system. If mem and cpus are omitted, resources are split equally. ETEXI -DEF("fda", HAS_ARG, QEMU_OPTION_fda, - "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) -DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) -STEXI -@item -fda @var{file} -@item -fdb @var{file} -@findex -fda -@findex -fdb -Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can -use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}). -ETEXI - -DEF("hda", HAS_ARG, QEMU_OPTION_hda, - "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) -DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) -DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, - "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) -DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) -STEXI -@item -hda @var{file} -@item -hdb @var{file} -@item -hdc @var{file} -@item -hdd @var{file} -@findex -hda -@findex -hdb -@findex -hdc -@findex -hdd -Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). -ETEXI - -DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, - "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", - QEMU_ARCH_ALL) -STEXI -@item -cdrom @var{file} -@findex -cdrom -Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and -@option{-cdrom} at the same time). You can use the host CD-ROM by -using @file{/dev/cdrom} as filename (@pxref{host_drives}). -ETEXI - -DEF("drive", HAS_ARG, QEMU_OPTION_drive, - "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" - " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" - " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" - " [,serial=s][,addr=A][,id=name][,aio=threads|native]\n" - " [,readonly=on|off][,copy-on-read=on|off]\n" - " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]][[,iops=i]|[[,iops_rd=r][,iops_wr=w]]\n" - " use 'file' as a drive image\n", QEMU_ARCH_ALL) -STEXI -@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] -@findex -drive - -Define a new drive. Valid options are: - -@table @option -@item file=@var{file} -This option defines which disk image (@pxref{disk_images}) 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. -@item if=@var{interface} -This option defines on which type on interface the drive is connected. -Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. -@item bus=@var{bus},unit=@var{unit} -These options define where is connected the drive by defining the bus number and -the unit id. -@item index=@var{index} -This option defines where is connected the drive by using an index in the list -of available connectors of a given interface type. -@item media=@var{media} -This option defines the type of the media: disk or cdrom. -@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] -These options have the same definition as they have in @option{-hdachs}. -@item snapshot=@var{snapshot} -@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}). -@item cache=@var{cache} -@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. -@item aio=@var{aio} -@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. -@item format=@var{format} -Specify which disk @var{format} will be used rather than detecting -the format. Can be used to specifiy format=raw to avoid interpreting -an untrusted format header. -@item serial=@var{serial} -This option specifies the serial number to assign to the device. -@item addr=@var{addr} -Specify the controller's PCI address (if=virtio only). -@item werror=@var{action},rerror=@var{action} -Specify which @var{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 @option{werror=enospc} and @option{rerror=report}. -@item readonly -Open drive @option{file} as read-only. Guest write attempts will fail. -@item copy-on-read=@var{copy-on-read} -@var{copy-on-read} is "on" or "off" and enables whether to copy read backing -file sectors into the image file. -@end table - -By default, the @option{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 @option{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 @option{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 -@option{cache=directsync}. - -In case you don't care about data integrity over host failures, use -@option{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 @option{-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 @option{-cdrom} you can use: -@example -qemu-system-i386 -drive file=file,index=2,media=cdrom -@end example - -Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can -use: -@example -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 -@end example - -You can open an image using pre-opened file descriptors from an fd set: -@example -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 -@end example - -You can connect a CDROM to the slave of ide0: -@example -qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom -@end example - -If you don't specify the "file=" argument, you define an empty drive: -@example -qemu-system-i386 -drive if=ide,index=1,media=cdrom -@end example - -You can connect a SCSI disk with unit ID 6 on the bus #0: -@example -qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 -@end example - -Instead of @option{-fda}, @option{-fdb}, you can use: -@example -qemu-system-i386 -drive file=file,index=0,if=floppy -qemu-system-i386 -drive file=file,index=1,if=floppy -@end example - -By default, @var{interface} is "ide" and @var{index} is automatically -incremented: -@example -qemu-system-i386 -drive file=a -drive file=b" -@end example -is interpreted like: -@example -qemu-system-i386 -hda a -hdb b -@end example -ETEXI - DEF("add-fd", HAS_ARG, QEMU_OPTION_add_fd, "-add-fd fd=fd,set=set[,opaque=opaque]\n" " Add 'fd' to fd 'set'\n", QEMU_ARCH_ALL) @@ -349,41 +159,16 @@ created automatically by the machine model. To create a device which is not created automatically and set properties on it, use -@option{device}. ETEXI -DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, - "-mtdblock file use 'file' as on-board Flash memory image\n", - QEMU_ARCH_ALL) -STEXI -@item -mtdblock @var{file} -@findex -mtdblock -Use @var{file} as on-board Flash memory image. -ETEXI - -DEF("sd", HAS_ARG, QEMU_OPTION_sd, - "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) -STEXI -@item -sd @var{file} -@findex -sd -Use @var{file} as SecureDigital card image. -ETEXI - -DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, - "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) -STEXI -@item -pflash @var{file} -@findex -pflash -Use @var{file} as a parallel flash image. -ETEXI - DEF("boot", HAS_ARG, QEMU_OPTION_boot, "-boot [order=drives][,once=drives][,menu=on|off]\n" - " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time]\n" + " [,splash=sp_name][,splash-time=sp_time][,reboot-timeout=rb_time][,strict=on|off]\n" " 'drives': floppy (a), hard disk (c), CD-ROM (d), network (n)\n" " 'sp_name': the file's name that would be passed to bios as logo picture, if menu=on\n" " 'sp_time': the period that splash picture last if menu=on, unit is ms\n" " 'rb_timeout': the timeout before guest reboot when boot failed, unit is ms\n", QEMU_ARCH_ALL) STEXI -@item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}] +@item -boot [order=@var{drives}][,once=@var{drives}][,menu=on|off][,splash=@var{sp_name}][,splash-time=@var{sp_time}][,reboot-timeout=@var{rb_timeout}][,strict=on|off] @findex -boot Specify boot order @var{drives} as a string of drive letters. Valid drive letters depend on the target achitecture. The x86 PC uses: a, b @@ -407,6 +192,10 @@ when boot failed, then reboot. If @var{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 @option{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. + @example # try to boot from network first, then from hard disk qemu-system-i386 -boot order=nc @@ -420,17 +209,6 @@ Note: The legacy format '-boot @var{drives}' is still supported but its use is discouraged as it may be removed from future versions. ETEXI -DEF("snapshot", 0, QEMU_OPTION_snapshot, - "-snapshot write to temporary files instead of disk image files\n", - QEMU_ARCH_ALL) -STEXI -@item -snapshot -@findex -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 @key{C-a s} (@pxref{disk_images}). -ETEXI - DEF("m", HAS_ARG, QEMU_OPTION_m, "-m megs set virtual RAM size to megs MB [default=" stringify(DEFAULT_RAM_SIZE) "]\n", QEMU_ARCH_ALL) @@ -535,94 +313,300 @@ Enable virtio balloon device (default), optionally with PCI address @var{addr}. ETEXI +DEF("device", HAS_ARG, QEMU_OPTION_device, + "-device driver[,prop[=value][,...]]\n" + " add device (based on driver)\n" + " prop=value,... sets driver properties\n" + " use '-device help' to print all possible drivers\n" + " use '-device driver,help' to print all possible properties\n", + QEMU_ARCH_ALL) +STEXI +@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] +@findex -device +Add device @var{driver}. @var{prop}=@var{value} sets driver +properties. Valid properties depend on the driver. To get help on +possible drivers and properties, use @code{-device help} and +@code{-device @var{driver},help}. +ETEXI + +DEF("name", HAS_ARG, QEMU_OPTION_name, + "-name string1[,process=string2]\n" + " set the name of the guest\n" + " string1 sets the window title and string2 the process name (on Linux)\n", + QEMU_ARCH_ALL) +STEXI +@item -name @var{name} +@findex -name +Sets the @var{name} of the guest. +This name will be displayed in the SDL window caption. +The @var{name} will also be used for the VNC server. +Also optionally set the top visible process name in Linux. +ETEXI + +DEF("uuid", HAS_ARG, QEMU_OPTION_uuid, + "-uuid %08x-%04x-%04x-%04x-%012x\n" + " specify machine UUID\n", QEMU_ARCH_ALL) +STEXI +@item -uuid @var{uuid} +@findex -uuid +Set system UUID. +ETEXI + STEXI @end table ETEXI DEFHEADING() -DEFHEADING(USB options:) +DEFHEADING(Block device options:) STEXI @table @option ETEXI -DEF("usb", 0, QEMU_OPTION_usb, - "-usb enable the USB driver (will be the default soon)\n", - QEMU_ARCH_ALL) +DEF("fda", HAS_ARG, QEMU_OPTION_fda, + "-fda/-fdb file use 'file' as floppy disk 0/1 image\n", QEMU_ARCH_ALL) +DEF("fdb", HAS_ARG, QEMU_OPTION_fdb, "", QEMU_ARCH_ALL) STEXI -@item -usb -@findex -usb -Enable the USB driver (will be the default soon) +@item -fda @var{file} +@item -fdb @var{file} +@findex -fda +@findex -fdb +Use @var{file} as floppy disk 0/1 image (@pxref{disk_images}). You can +use the host floppy by using @file{/dev/fd0} as filename (@pxref{host_drives}). ETEXI -DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, - "-usbdevice name add the host or guest USB device 'name'\n", +DEF("hda", HAS_ARG, QEMU_OPTION_hda, + "-hda/-hdb file use 'file' as IDE hard disk 0/1 image\n", QEMU_ARCH_ALL) +DEF("hdb", HAS_ARG, QEMU_OPTION_hdb, "", QEMU_ARCH_ALL) +DEF("hdc", HAS_ARG, QEMU_OPTION_hdc, + "-hdc/-hdd file use 'file' as IDE hard disk 2/3 image\n", QEMU_ARCH_ALL) +DEF("hdd", HAS_ARG, QEMU_OPTION_hdd, "", QEMU_ARCH_ALL) +STEXI +@item -hda @var{file} +@item -hdb @var{file} +@item -hdc @var{file} +@item -hdd @var{file} +@findex -hda +@findex -hdb +@findex -hdc +@findex -hdd +Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). +ETEXI + +DEF("cdrom", HAS_ARG, QEMU_OPTION_cdrom, + "-cdrom file use 'file' as IDE cdrom image (cdrom is ide1 master)\n", QEMU_ARCH_ALL) STEXI +@item -cdrom @var{file} +@findex -cdrom +Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and +@option{-cdrom} at the same time). You can use the host CD-ROM by +using @file{/dev/cdrom} as filename (@pxref{host_drives}). +ETEXI -@item -usbdevice @var{devname} -@findex -usbdevice -Add the USB device @var{devname}. @xref{usb_devices}. +DEF("drive", HAS_ARG, QEMU_OPTION_drive, + "-drive [file=file][,if=type][,bus=n][,unit=m][,media=d][,index=i]\n" + " [,cyls=c,heads=h,secs=s[,trans=t]][,snapshot=on|off]\n" + " [,cache=writethrough|writeback|none|directsync|unsafe][,format=f]\n" + " [,serial=s][,addr=A][,id=name][,aio=threads|native]\n" + " [,readonly=on|off][,copy-on-read=on|off]\n" + " [[,bps=b]|[[,bps_rd=r][,bps_wr=w]]]\n" + " [[,iops=i]|[[,iops_rd=r][,iops_wr=w]]]\n" + " [[,bps_max=bm]|[[,bps_rd_max=rm][,bps_wr_max=wm]]]\n" + " [[,iops_max=im]|[[,iops_rd_max=irm][,iops_wr_max=iwm]]]\n" + " [[,iops_size=is]]\n" + " use 'file' as a drive image\n", QEMU_ARCH_ALL) +STEXI +@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] +@findex -drive + +Define a new drive. Valid options are: @table @option +@item file=@var{file} +This option defines which disk image (@pxref{disk_images}) to use with +this drive. If the filename contains comma, you must double it +(for instance, "file=my,,file" to use file "my,file"). -@item mouse -Virtual Mouse. This will override the PS/2 mouse emulation when activated. +Special files such as iSCSI devices can be specified using protocol +specific URLs. See the section for "Device URL Syntax" for more information. +@item if=@var{interface} +This option defines on which type on interface the drive is connected. +Available types are: ide, scsi, sd, mtd, floppy, pflash, virtio. +@item bus=@var{bus},unit=@var{unit} +These options define where is connected the drive by defining the bus number and +the unit id. +@item index=@var{index} +This option defines where is connected the drive by using an index in the list +of available connectors of a given interface type. +@item media=@var{media} +This option defines the type of the media: disk or cdrom. +@item cyls=@var{c},heads=@var{h},secs=@var{s}[,trans=@var{t}] +These options have the same definition as they have in @option{-hdachs}. +@item snapshot=@var{snapshot} +@var{snapshot} is "on" or "off" and allows to enable snapshot for given drive (see @option{-snapshot}). +@item cache=@var{cache} +@var{cache} is "none", "writeback", "unsafe", "directsync" or "writethrough" and controls how the host cache is used to access block data. +@item aio=@var{aio} +@var{aio} is "threads", or "native" and selects between pthread based disk I/O and native Linux AIO. +@item discard=@var{discard} +@var{discard} is one of "ignore" (or "off") or "unmap" (or "on") and controls whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap}) requests are ignored or passed to the filesystem. Some machine types may not support discard requests. +@item format=@var{format} +Specify which disk @var{format} will be used rather than detecting +the format. Can be used to specifiy format=raw to avoid interpreting +an untrusted format header. +@item serial=@var{serial} +This option specifies the serial number to assign to the device. +@item addr=@var{addr} +Specify the controller's PCI address (if=virtio only). +@item werror=@var{action},rerror=@var{action} +Specify which @var{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 @option{werror=enospc} and @option{rerror=report}. +@item readonly +Open drive @option{file} as read-only. Guest write attempts will fail. +@item copy-on-read=@var{copy-on-read} +@var{copy-on-read} is "on" or "off" and enables whether to copy read backing +file sectors into the image file. +@end table -@item 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. +By default, the @option{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. -@item disk:[format=@var{format}]:@var{file} -Mass storage device based on file. The optional @var{format} argument -will be used rather than detecting the format. Can be used to specifiy -@code{format=raw} to avoid interpreting an untrusted format header. +For such guests, you should consider using @option{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 @option{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 +@option{cache=directsync}. + +In case you don't care about data integrity over host failures, use +@option{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 @option{-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 @option{-cdrom} you can use: +@example +qemu-system-i386 -drive file=file,index=2,media=cdrom +@end example + +Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can +use: +@example +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 +@end example -@item host:@var{bus}.@var{addr} -Pass through the host device identified by @var{bus}.@var{addr} (Linux only). +You can open an image using pre-opened file descriptors from an fd set: +@example +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 +@end example -@item host:@var{vendor_id}:@var{product_id} -Pass through the host device identified by @var{vendor_id}:@var{product_id} -(Linux only). +You can connect a CDROM to the slave of ide0: +@example +qemu-system-i386 -drive file=file,if=ide,index=1,media=cdrom +@end example -@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} -Serial converter to host character device @var{dev}, see @code{-serial} for the -available devices. +If you don't specify the "file=" argument, you define an empty drive: +@example +qemu-system-i386 -drive if=ide,index=1,media=cdrom +@end example -@item braille -Braille device. This will use BrlAPI to display the braille output on a real -or fake device. +You can connect a SCSI disk with unit ID 6 on the bus #0: +@example +qemu-system-i386 -drive file=file,if=scsi,bus=0,unit=6 +@end example -@item net:@var{options} -Network adapter that supports CDC ethernet and RNDIS protocols. +Instead of @option{-fda}, @option{-fdb}, you can use: +@example +qemu-system-i386 -drive file=file,index=0,if=floppy +qemu-system-i386 -drive file=file,index=1,if=floppy +@end example -@end table +By default, @var{interface} is "ide" and @var{index} is automatically +incremented: +@example +qemu-system-i386 -drive file=a -drive file=b" +@end example +is interpreted like: +@example +qemu-system-i386 -hda a -hdb b +@end example ETEXI -DEF("device", HAS_ARG, QEMU_OPTION_device, - "-device driver[,prop[=value][,...]]\n" - " add device (based on driver)\n" - " prop=value,... sets driver properties\n" - " use '-device help' to print all possible drivers\n" - " use '-device driver,help' to print all possible properties\n", +DEF("mtdblock", HAS_ARG, QEMU_OPTION_mtdblock, + "-mtdblock file use 'file' as on-board Flash memory image\n", QEMU_ARCH_ALL) STEXI -@item -device @var{driver}[,@var{prop}[=@var{value}][,...]] -@findex -device -Add device @var{driver}. @var{prop}=@var{value} sets driver -properties. Valid properties depend on the driver. To get help on -possible drivers and properties, use @code{-device help} and -@code{-device @var{driver},help}. +@item -mtdblock @var{file} +@findex -mtdblock +Use @var{file} as on-board Flash memory image. ETEXI +DEF("sd", HAS_ARG, QEMU_OPTION_sd, + "-sd file use 'file' as SecureDigital card image\n", QEMU_ARCH_ALL) STEXI -@end table +@item -sd @var{file} +@findex -sd +Use @var{file} as SecureDigital card image. ETEXI -DEFHEADING() -DEFHEADING(File system options:) +DEF("pflash", HAS_ARG, QEMU_OPTION_pflash, + "-pflash file use 'file' as a parallel flash image\n", QEMU_ARCH_ALL) STEXI -@table @option +@item -pflash @var{file} +@findex -pflash +Use @var{file} as a parallel flash image. +ETEXI + +DEF("snapshot", 0, QEMU_OPTION_snapshot, + "-snapshot write to temporary files instead of disk image files\n", + QEMU_ARCH_ALL) +STEXI +@item -snapshot +@findex -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 @key{C-a s} (@pxref{disk_images}). +ETEXI + +DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ + "-hdachs c,h,s[,t]\n" \ + " force hard disk 0 physical geometry and the optional BIOS\n" \ + " translation (t=none or lba) (usually QEMU can guess them)\n", + QEMU_ARCH_ALL) +STEXI +@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] +@findex -hdachs +Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= +@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS +translation mode (@var{t}=none, lba or auto). Usually QEMU can guess +all those parameters. This option is useful for old MS-DOS disk +images. ETEXI DEF("fsdev", HAS_ARG, QEMU_OPTION_fsdev, @@ -687,16 +671,6 @@ Specifies the tag name to be used by the guest to mount this export point ETEXI -STEXI -@end table -ETEXI -DEFHEADING() - -DEFHEADING(Virtual File system pass-through options:) -STEXI -@table @option -ETEXI - DEF("virtfs", HAS_ARG, QEMU_OPTION_virtfs, "-virtfs local,path=path,mount_tag=tag,security_model=[mapped-xattr|mapped-file|passthrough|none]\n" " [,writeout=immediate][,readonly][,socket=socket|sock_fd=sock_fd]\n", @@ -758,29 +732,68 @@ STEXI Create synthetic file system image ETEXI +STEXI +@end table +ETEXI DEFHEADING() -DEF("name", HAS_ARG, QEMU_OPTION_name, - "-name string1[,process=string2]\n" - " set the name of the guest\n" - " string1 sets the window title and string2 the process name (on Linux)\n", +DEFHEADING(USB options:) +STEXI +@table @option +ETEXI + +DEF("usb", 0, QEMU_OPTION_usb, + "-usb enable the USB driver (will be the default soon)\n", QEMU_ARCH_ALL) STEXI -@item -name @var{name} -@findex -name -Sets the @var{name} of the guest. -This name will be displayed in the SDL window caption. -The @var{name} will also be used for the VNC server. -Also optionally set the top visible process name in Linux. +@item -usb +@findex -usb +Enable the USB driver (will be the default soon) ETEXI -DEF("uuid", HAS_ARG, QEMU_OPTION_uuid, - "-uuid %08x-%04x-%04x-%04x-%012x\n" - " specify machine UUID\n", QEMU_ARCH_ALL) +DEF("usbdevice", HAS_ARG, QEMU_OPTION_usbdevice, + "-usbdevice name add the host or guest USB device 'name'\n", + QEMU_ARCH_ALL) STEXI -@item -uuid @var{uuid} -@findex -uuid -Set system UUID. + +@item -usbdevice @var{devname} +@findex -usbdevice +Add the USB device @var{devname}. @xref{usb_devices}. + +@table @option + +@item mouse +Virtual Mouse. This will override the PS/2 mouse emulation when activated. + +@item 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. + +@item disk:[format=@var{format}]:@var{file} +Mass storage device based on file. The optional @var{format} argument +will be used rather than detecting the format. Can be used to specifiy +@code{format=raw} to avoid interpreting an untrusted format header. + +@item host:@var{bus}.@var{addr} +Pass through the host device identified by @var{bus}.@var{addr} (Linux only). + +@item host:@var{vendor_id}:@var{product_id} +Pass through the host device identified by @var{vendor_id}:@var{product_id} +(Linux only). + +@item serial:[vendorid=@var{vendor_id}][,productid=@var{product_id}]:@var{dev} +Serial converter to host character device @var{dev}, see @code{-serial} for the +available devices. + +@item braille +Braille device. This will use BrlAPI to display the braille output on a real +or fake device. + +@item net:@var{options} +Network adapter that supports CDC ethernet and RNDIS protocols. + +@end table ETEXI STEXI @@ -833,8 +846,10 @@ STEXI Normally, QEMU uses SDL to display the VGA output. With this option, you can totally disable graphical output so that QEMU is a simple command line application. The emulated serial port is redirected on -the console. Therefore, you can still use QEMU to debug a Linux kernel -with a serial console. +the console and muxed with the monitor (unless redirected elsewhere +explicitly). Therefore, you can still use QEMU to debug a Linux kernel +with a serial console. Use @key{C-a h} for help on switching between +the console and monitor. ETEXI DEF("curses", 0, QEMU_OPTION_curses, @@ -908,8 +923,8 @@ DEF("spice", HAS_ARG, QEMU_OPTION_spice, " [,jpeg-wan-compression=[auto|never|always]]\n" " [,zlib-glz-wan-compression=[auto|never|always]]\n" " [,streaming-video=[off|all|filter]][,disable-copy-paste]\n" - " [,agent-mouse=[on|off]][,playback-compression=[on|off]]\n" - " [,seamless-migration=[on|off]]\n" + " [,disable-agent-file-xfer][,agent-mouse=[on|off]]\n" + " [,playback-compression=[on|off]][,seamless-migration=[on|off]]\n" " enable spice\n" " at least one of {port, tls-port} is mandatory\n", QEMU_ARCH_ALL) @@ -952,6 +967,9 @@ Allow client connects without authentication. @item disable-copy-paste Disable copy paste between the client and the guest. +@item disable-agent-file-xfer +Disable spice-vdagent based file-xfer between the client and the guest. + @item tls-port= Set the TCP port spice is listening on for encrypted channels. @@ -1114,10 +1132,12 @@ is a TCP port number, not a display number. @item websocket Opens an additional TCP listening port dedicated to VNC Websocket connections. -By defintion the Websocket port is 5700+@var{display}. If @var{host} is +By definition the Websocket port is 5700+@var{display}. If @var{host} is specified connections will only be allowed from this host. As an alternative the Websocket port could be specified by using @code{websocket}=@var{port}. +TLS encryption for the Websocket connection is supported if the required +certificates are specified with the VNC option @option{x509}. @item password @@ -1257,9 +1277,8 @@ DEF("no-fd-bootchk", 0, QEMU_OPTION_no_fd_bootchk, STEXI @item -no-fd-bootchk @findex -no-fd-bootchk -Disable boot signature checking for floppy disks in Bochs BIOS. It may +Disable boot signature checking for floppy disks in BIOS. May be needed to boot from old floppy disks. -TODO: check reference to Bochs BIOS. ETEXI DEF("no-acpi", 0, QEMU_OPTION_no_acpi, @@ -1351,7 +1370,7 @@ DEF("net", HAS_ARG, QEMU_OPTION_net, "-net tap[,vlan=n][,name=str],ifname=name\n" " connect the host TAP network interface to VLAN 'n'\n" #else - "-net tap[,vlan=n][,name=str][,fd=h][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostforce=on|off]\n" + "-net tap[,vlan=n][,name=str][,fd=h][,fds=x:y:...:z][,ifname=name][,script=file][,downscript=dfile][,helper=helper][,sndbuf=nbytes][,vnet_hdr=on|off][,vhost=on|off][,vhostfd=h][,vhostfds=x:y:...:z][,vhostforce=on|off][,queues=n]\n" " connect the host TAP network interface to VLAN 'n'\n" " use network scripts 'file' (default=" DEFAULT_NETWORK_SCRIPT ")\n" " to configure it and 'dfile' (default=" DEFAULT_NETWORK_DOWN_SCRIPT ")\n" @@ -1360,6 +1379,7 @@ DEF("net", HAS_ARG, QEMU_OPTION_net, " use network helper 'helper' (default=" DEFAULT_BRIDGE_HELPER ") to\n" " configure it\n" " use 'fd=h' to connect to an already opened TAP interface\n" + " use 'fds=x:y:...:z' to connect to already opened multiqueue capable TAP interfaces\n" " use 'sndbuf=nbytes' to limit the size of the send buffer (the\n" " default is disabled 'sndbuf=0' to enable flow control set 'sndbuf=1048576')\n" " use vnet_hdr=off to avoid enabling the IFF_VNET_HDR tap flag\n" @@ -1368,6 +1388,8 @@ DEF("net", HAS_ARG, QEMU_OPTION_net, " (only has effect for virtio guests which use MSIX)\n" " use vhostforce=on to force vhost on for non-MSIX virtio guests\n" " use 'vhostfd=h' to connect to an already opened vhost net device\n" + " use 'vhostfds=x:y:...:z to connect to multiple already opened vhost net devices\n" + " use 'queues=n' to specify the number of queues to be created for multiqueue TAP\n" "-net bridge[,vlan=n][,name=str][,br=bridge][,helper=helper]\n" " connects a host TAP network interface to a host bridge device 'br'\n" " (default=" DEFAULT_BRIDGE_INTERFACE ") using the program 'helper'\n" @@ -1401,7 +1423,8 @@ DEF("netdev", HAS_ARG, QEMU_OPTION_netdev, #ifdef CONFIG_VDE "vde|" #endif - "socket],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL) + "socket|" + "hubport],id=str[,option][,option][,...]\n", QEMU_ARCH_ALL) STEXI @item -net nic[,vlan=@var{n}][,macaddr=@var{mac}][,model=@var{type}] [,name=@var{name}][,addr=@var{addr}][,vectors=@var{v}] @findex -net @@ -1723,6 +1746,14 @@ vde_switch -F -sock /tmp/myswitch qemu-system-i386 linux.img -net nic -net vde,sock=/tmp/myswitch @end example +@item -netdev hubport,id=@var{id},hubid=@var{hubid} + +Create a hub port on QEMU "vlan" @var{hubid}. + +The hubport netdev lets you connect a NIC to a QEMU "vlan" instead of a single +netdev. @code{-net} and @code{-device} with parameter @option{vlan} create the +required hub automatically. + @item -net dump[,vlan=@var{n}][,file=@var{file}][,len=@var{len}] Dump network traffic on VLAN @var{n} to file @var{file} (@file{qemu-vlan0.pcap} by default). At most @var{len} bytes (64k by default) per packet are stored. The file format is @@ -2086,29 +2117,31 @@ Example for Unix Domain Sockets qemu-system-i386 --drive file=nbd:unix:/tmp/nbd-socket @end example +@item SSH +QEMU supports SSH (Secure Shell) access to remote disks. + +Examples: +@example +qemu-system-i386 -drive file=ssh://user@@host/path/to/disk.img +qemu-system-i386 -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img +@end example + +Currently authentication must be done using ssh-agent. Other +authentication methods may be supported in future. + @item Sheepdog Sheepdog is a distributed storage system for QEMU. QEMU supports using either local sheepdog devices or remote networked devices. Syntax for specifying a sheepdog device -@table @list -``sheepdog:'' - -``sheepdog::'' - -``sheepdog::'' - -``sheepdog:::'' - -``sheepdog::::'' - -``sheepdog::::'' -@end table +@example +sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] +@end example Example @example -qemu-system-i386 --drive file=sheepdog:192.0.2.1:30000:MyVirtualMachine +qemu-system-i386 --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine @end example See also @url{http://http://www.osrg.net/sheepdog/}. @@ -2126,7 +2159,7 @@ gluster[+transport]://[server[:port]]/volname/image[?socket=...] Example @example -qemu-system-x86_84 --drive file=gluster://192.0.2.1/testvol/a.img +qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img @end example See also @url{http://www.gluster.org}. @@ -2211,6 +2244,81 @@ STEXI ETEXI DEFHEADING() +#ifdef CONFIG_TPM +DEFHEADING(TPM device options:) + +DEF("tpmdev", HAS_ARG, QEMU_OPTION_tpmdev, \ + "-tpmdev passthrough,id=id[,path=path][,cancel-path=path]\n" + " use path to provide path to a character device; default is /dev/tpm0\n" + " use cancel-path to provide path to TPM's cancel sysfs entry; if\n" + " not provided it will be searched for in /sys/class/misc/tpm?/device\n", + QEMU_ARCH_ALL) +STEXI + +The general form of a TPM device option is: +@table @option + +@item -tpmdev @var{backend} ,id=@var{id} [,@var{options}] +@findex -tpmdev +Backend type must be: +@option{passthrough}. + +The specific backend type will determine the applicable options. +The @code{-tpmdev} option creates the TPM backend and requires a +@code{-device} option that specifies the TPM frontend interface model. + +Options to each backend are described below. + +Use 'help' to print all available TPM backend types. +@example +qemu -tpmdev help +@end example + +@item -tpmdev passthrough, id=@var{id}, path=@var{path}, cancel-path=@var{cancel-path} + +(Linux-host only) Enable access to the host's TPM using the passthrough +driver. + +@option{path} specifies the path to the host's TPM device, i.e., on +a Linux host this would be @code{/dev/tpm0}. +@option{path} is optional and by default @code{/dev/tpm0} is used. + +@option{cancel-path} specifies the path to the host TPM device's sysfs +entry allowing for cancellation of an ongoing TPM command. +@option{cancel-path} is optional and by default QEMU will search for the +sysfs entry to use. + +Some notes about using the host's TPM with the passthrough driver: + +The TPM device accessed by the passthrough driver must not be +used by any other application on the host. + +Since the host's firmware (BIOS/UEFI) has already initialized the TPM, +the VM's firmware (BIOS/UEFI) will not be able to initialize the +TPM again and may therefore not show a TPM-specific menu that would +otherwise allow the user to configure the TPM, e.g., allow the user to +enable/disable or activate/deactivate the TPM. +Further, if TPM ownership is released from within a VM then the host's TPM +will get disabled and deactivated. To enable and activate the +TPM again afterwards, the host has to be rebooted and the user is +required to enter the firmware's menu to enable and activate the TPM. +If the TPM is left disabled and/or deactivated most TPM commands will fail. + +To create a passthrough TPM use the following two options: +@example +-tpmdev passthrough,id=tpm0 -device tpm-tis,tpmdev=tpm0 +@end example +Note that the @code{-tpmdev} id is @code{tpm0} and is referenced by +@code{tpmdev=tpm0} in the device option. + +@end table + +ETEXI + +DEFHEADING() + +#endif + DEFHEADING(Linux/Multiboot boot specific:) STEXI @@ -2383,14 +2491,15 @@ same as if you had specified @code{-serial tcp} except the unix domain socket @item mon:@var{dev_string} This is a special option to allow the monitor to be multiplexed onto another serial port. The monitor is accessed with key sequence of -@key{Control-a} and then pressing @key{c}. See monitor access -@ref{pcsys_keys} in the -nographic section for more keys. +@key{Control-a} and then pressing @key{c}. @var{dev_string} should be any one of the serial devices specified above. An example to multiplex the monitor onto a telnet server listening on port 4444 would be: @table @code @item -serial mon:telnet::4444,server,nowait @end table +When the monitor is multiplexed to stdio in this way, Ctrl+C will not terminate +QEMU any more but will be passed to the guest instead. @item braille Braille device. This will use BrlAPI to display the braille output on a real @@ -2428,6 +2537,7 @@ Redirect the monitor to host device @var{dev} (same devices as the serial port). The default device is @code{vc} in graphical mode and @code{stdio} in non graphical mode. +Use @code{-monitor none} to disable the default monitor. ETEXI DEF("qmp", HAS_ARG, QEMU_OPTION_qmp, \ "-qmp dev like -monitor but opens in 'control' mode\n", @@ -2439,9 +2549,9 @@ Like -monitor but opens in 'control' mode. ETEXI DEF("mon", HAS_ARG, QEMU_OPTION_mon, \ - "-mon chardev=[name][,mode=readline|control][,default]\n", QEMU_ARCH_ALL) + "-mon [chardev=]name[,mode=readline|control][,default]\n", QEMU_ARCH_ALL) STEXI -@item -mon chardev=[name][,mode=readline|control][,default] +@item -mon [chardev=]name[,mode=readline|control][,default] @findex -mon Setup monitor on chardev @var{name}. ETEXI @@ -2485,6 +2595,19 @@ STEXI Do not start CPU at startup (you must type 'c' in the monitor). ETEXI +DEF("realtime", HAS_ARG, QEMU_OPTION_realtime, + "-realtime [mlock=on|off]\n" + " run qemu with realtime features\n" + " mlock=on|off controls mlock support (default: on)\n", + QEMU_ARCH_ALL) +STEXI +@item -realtime mlock=on|off +@findex -realtime +Run qemu with realtime features. +mlocking qemu and guest memory can be enabled via @option{mlock=on} +(enabled by default). +ETEXI + DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) STEXI @@ -2510,36 +2633,21 @@ Shorthand for -gdb tcp::1234, i.e. open a gdbserver on TCP port 1234 ETEXI DEF("d", HAS_ARG, QEMU_OPTION_d, \ - "-d item1,... output log to /tmp/qemu.log (use '-d help' for a list of log items)\n", + "-d item1,... enable logging of specified items (use '-d help' for a list of log items)\n", QEMU_ARCH_ALL) STEXI -@item -d +@item -d @var{item1}[,...] @findex -d -Output log in /tmp/qemu.log +Enable logging of specified items. Use '-d help' for a list of log items. ETEXI DEF("D", HAS_ARG, QEMU_OPTION_D, \ - "-D logfile output log to logfile (instead of the default /tmp/qemu.log)\n", + "-D logfile output log to logfile (default stderr)\n", QEMU_ARCH_ALL) STEXI @item -D @var{logfile} @findex -D -Output log in @var{logfile} instead of /tmp/qemu.log -ETEXI - -DEF("hdachs", HAS_ARG, QEMU_OPTION_hdachs, \ - "-hdachs c,h,s[,t]\n" \ - " force hard disk 0 physical geometry and the optional BIOS\n" \ - " translation (t=none or lba) (usually QEMU can guess them)\n", - QEMU_ARCH_ALL) -STEXI -@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] -@findex -hdachs -Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= -@var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS -translation mode (@var{t}=none, lba or auto). Usually QEMU can guess -all those parameters. This option is useful for old MS-DOS disk -images. +Output log in @var{logfile} instead of to stderr ETEXI DEF("L", HAS_ARG, QEMU_OPTION_L, \ @@ -2997,6 +3105,17 @@ property must be set. These objects are placed in the '/objects' path. ETEXI +DEF("msg", HAS_ARG, QEMU_OPTION_msg, + "-msg timestamp[=on|off]\n" + " change the format of messages\n" + " on|off controls leading timestamps (default:on)\n", + QEMU_ARCH_ALL) +STEXI +@item -msg timestamp[=on|off] +@findex -msg +prepend a timestamp to each log message.(default:on) +ETEXI + HXCOMM This is the last statement. Insert new options before this line! STEXI @end table