X-Git-Url: http://vcs.maemo.org/git/?a=blobdiff_plain;f=qemu-doc.texi;h=7747e2733d3c676e70db3d1c3ef8398904162534;hb=HEAD;hp=0d869ed192ca8e657bccbffdfa09eac278cecee7;hpb=fa879c641435bec4b79872ad14b9a90c8b7172f3;p=qemu diff --git a/qemu-doc.texi b/qemu-doc.texi index 0d869ed..7747e27 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -72,7 +72,7 @@ For system emulation, the following hardware targets are supported: @item PC (x86 or x86_64 processor) @item ISA PC (old style PC without PCI bus) @item PREP (PowerPC processor) -@item G3 BW PowerMac (PowerPC processor) +@item G3 Beige PowerMac (PowerPC processor) @item Mac99 PowerMac (PowerPC processor, in progress) @item Sun4m/Sun4c/Sun4d (32-bit Sparc processor) @item Sun4u/Sun4v (64-bit Sparc processor, in progress) @@ -91,9 +91,12 @@ For system emulation, the following hardware targets are supported: @item MusicPal (MV88W8618 ARM processor) @item Gumstix "Connex" and "Verdex" motherboards (PXA255/270). @item Siemens SX1 smartphone (OMAP310 processor) +@item Syborg SVP base model (ARM Cortex-A8). +@item AXIS-Devboard88 (CRISv32 ETRAX-FS). +@item Petalogix Spartan 3aDSP1800 MMU ref design (MicroBlaze). @end itemize -For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported. +For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64, ColdFire(m68k), CRISv32 and MicroBlaze CPUs are supported. @node Installation @chapter Installation @@ -163,7 +166,7 @@ PS/2 mouse and keyboard @item Floppy disk @item -PCI/ISA PCI network adapters +PCI and ISA network adapters @item Serial ports @item @@ -184,8 +187,8 @@ PCI UHCI USB controller and a virtual USB hub. SMP is supported with up to 255 CPUs. -Note that adlib, ac97, gus and cs4231a are only available when QEMU -was configured with --audio-card-list option containing the name(s) of +Note that adlib, gus and cs4231a are only available when QEMU was +configured with --audio-card-list option containing the name(s) of required card(s). QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL @@ -221,881 +224,10 @@ usage: qemu [options] [@var{disk_image}] @end example @c man begin OPTIONS -@var{disk_image} is a raw hard disk image for IDE hard disk 0. +@var{disk_image} is a raw hard disk image for IDE hard disk 0. Some +targets do not need a disk image. -General options: -@table @option -@item -M @var{machine} -Select the emulated @var{machine} (@code{-M ?} for list) - -@item -fda @var{file} -@item -fdb @var{file} -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}). - -@item -hda @var{file} -@item -hdb @var{file} -@item -hdc @var{file} -@item -hdd @var{file} -Use @var{file} as hard disk 0, 1, 2 or 3 image (@pxref{disk_images}). - -@item -cdrom @var{file} -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}). - -@item -drive @var{option}[,@var{option}[,@var{option}[,...]]] - -Define a new drive. Valid options are: - -@table @code -@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 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", or "writethrough" and controls how the host cache is used to access block data. -@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. -@end table - -By default, writethrough caching is used for all block device. 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 when the data has been reported as written by -the storage subsystem. - -Writeback caching will report data writes as completed as soon as the data is -present in the host page cache. This is safe as long as you trust your host. -If your host crashes or loses power, then the guest may experience data -corruption. When using the @option{-snapshot} option, writeback caching is -used by default. - -The host page can be avoided entirely with @option{cache=none}. This will -attempt to do disk IO directly to the guests memory. QEMU may still perform -an internal copy of the data. - -Some block drivers perform badly with @option{cache=writethrough}, most notably, -qcow2. If performance is more important than correctness, -@option{cache=writeback} should be used with qcow2. By default, if no explicit -caching is specified for a qcow2 disk image, @option{cache=writeback} will be -used. For all other disk types, @option{cache=writethrough} is the default. - -Instead of @option{-cdrom} you can use: -@example -qemu -drive file=file,index=2,media=cdrom -@end example - -Instead of @option{-hda}, @option{-hdb}, @option{-hdc}, @option{-hdd}, you can -use: -@example -qemu -drive file=file,index=0,media=disk -qemu -drive file=file,index=1,media=disk -qemu -drive file=file,index=2,media=disk -qemu -drive file=file,index=3,media=disk -@end example - -You can connect a CDROM to the slave of ide0: -@example -qemu -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 -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 -drive file=file,if=scsi,bus=0,unit=6 -@end example - -Instead of @option{-fda}, @option{-fdb}, you can use: -@example -qemu -drive file=file,index=0,if=floppy -qemu -drive file=file,index=1,if=floppy -@end example - -By default, @var{interface} is "ide" and @var{index} is automatically -incremented: -@example -qemu -drive file=a -drive file=b" -@end example -is interpreted like: -@example -qemu -hda a -hdb b -@end example - -@item -boot [a|c|d|n] -Boot on floppy (a), hard disk (c), CD-ROM (d), or Etherboot (n). Hard disk boot -is the default. - -@item -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}). - -@item -no-fd-bootchk -Disable boot signature checking for floppy disks in Bochs BIOS. It may -be needed to boot from old floppy disks. - -@item -m @var{megs} -Set virtual RAM size to @var{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. - -@item -cpu @var{model} -Select CPU model (-cpu ? for list and additional feature selection) - -@item -smp @var{n} -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 -to 4. - -@item -audio-help - -Will show the audio subsystem help: list of drivers, tunable -parameters. - -@item -soundhw @var{card1}[,@var{card2},...] or -soundhw all - -Enable audio and selected sound hardware. Use ? to print all -available sound hardware. - -@example -qemu -soundhw sb16,adlib disk.img -qemu -soundhw es1370 disk.img -qemu -soundhw ac97 disk.img -qemu -soundhw all disk.img -qemu -soundhw ? -@end example - -Note that Linux's i810_audio OSS kernel (for AC97) module might -require manually specifying clocking. - -@example -modprobe i810_audio clocking=48000 -@end example - -@item -localtime -Set the real time clock to local time (the default is to UTC -time). This option is needed to have correct date in MS-DOS or -Windows. - -@item -startdate @var{date} -Set the initial date of the real time clock. Valid formats for -@var{date} are: @code{now} or @code{2006-06-17T16:01:21} or -@code{2006-06-17}. The default value is @code{now}. - -@item -pidfile @var{file} -Store the QEMU process PID in @var{file}. It is useful if you launch QEMU -from a script. - -@item -daemonize -Daemonize the QEMU process after initialization. QEMU will not detach from -standard IO until it is ready to receive connections on any of its devices. -This option is a useful way for external programs to launch QEMU without having -to cope with initialization race conditions. - -@item -win2k-hack -Use it when installing Windows 2000 to avoid a disk full bug. After -Windows 2000 is installed, you no longer need this option (this option -slows down the IDE transfers). - -@item -option-rom @var{file} -Load the contents of @var{file} as an option ROM. -This option is useful to load things like EtherBoot. - -@item -name @var{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. - -@end table - -Display options: -@table @option - -@item -nographic - -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. - -@item -curses - -Normally, QEMU uses SDL to display the VGA output. With this option, -QEMU can display the VGA output when in text mode using a -curses/ncurses interface. Nothing is displayed in graphical mode. - -@item -no-frame - -Do not use decorations for SDL windows and start them using the whole -available screen space. This makes the using QEMU in a dedicated desktop -workspace more convenient. - -@item -no-quit - -Disable SDL window close capability. - -@item -full-screen -Start in full screen. - -@item -vnc @var{display}[,@var{option}[,@var{option}[,...]]] - -Normally, QEMU uses SDL to display the VGA output. With this option, -you can have QEMU listen on VNC display @var{display} and redirect the VGA -display over the VNC session. It is very useful to enable the usb -tablet device when using this option (option @option{-usbdevice -tablet}). When using the VNC display, you must use the @option{-k} -parameter to set the keyboard layout if you are not using en-us. Valid -syntax for the @var{display} is - -@table @code - -@item @var{host}:@var{d} - -TCP connections will only be allowed from @var{host} on display @var{d}. -By convention the TCP port is 5900+@var{d}. Optionally, @var{host} can -be omitted in which case the server will accept connections from any host. - -@item @code{unix}:@var{path} - -Connections will be allowed over UNIX domain sockets where @var{path} is the -location of a unix socket to listen for connections on. - -@item none - -VNC is initialized but not started. The monitor @code{change} command -can be used to later start the VNC server. - -@end table - -Following the @var{display} value there may be one or more @var{option} flags -separated by commas. Valid options are - -@table @code - -@item reverse - -Connect to a listening VNC client via a ``reverse'' connection. The -client is specified by the @var{display}. For reverse network -connections (@var{host}:@var{d},@code{reverse}), the @var{d} argument -is a TCP port number, not a display number. - -@item password - -Require that password based authentication is used for client connections. -The password must be set separately using the @code{change} command in the -@ref{pcsys_monitor} - -@item tls - -Require that client use TLS when communicating with the VNC server. This -uses anonymous TLS credentials so is susceptible to a man-in-the-middle -attack. It is recommended that this option be combined with either the -@var{x509} or @var{x509verify} options. - -@item x509=@var{/path/to/certificate/dir} - -Valid if @option{tls} is specified. Require that x509 credentials are used -for negotiating the TLS session. The server will send its x509 certificate -to the client. It is recommended that a password be set on the VNC server -to provide authentication of the client when this is used. The path following -this option specifies where the x509 certificates are to be loaded from. -See the @ref{vnc_security} section for details on generating certificates. - -@item x509verify=@var{/path/to/certificate/dir} - -Valid if @option{tls} is specified. Require that x509 credentials are used -for negotiating the TLS session. The server will send its x509 certificate -to the client, and request that the client send its own x509 certificate. -The server will validate the client's certificate against the CA certificate, -and reject clients when validation fails. If the certificate authority is -trusted, this is a sufficient authentication mechanism. You may still wish -to set a password on the VNC server as a second authentication layer. The -path following this option specifies where the x509 certificates are to -be loaded from. See the @ref{vnc_security} section for details on generating -certificates. - -@end table - -@item -k @var{language} - -Use keyboard layout @var{language} (for example @code{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: -@example -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 -@end example - -The default is @code{en-us}. - -@end table - -USB options: -@table @option - -@item -usb -Enable the USB driver (will be the default soon) - -@item -usbdevice @var{devname} -Add the USB device @var{devname}. @xref{usb_devices}. - -@table @code - -@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}]: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 -format=raw to avoid interpreting an untrusted format header. - -@item host:bus.addr -Pass through the host device identified by bus.addr (Linux only). - -@item host:vendor_id:product_id -Pass through the host device identified by vendor_id: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:options -Network adapter that supports CDC ethernet and RNDIS protocols. - -@end table - -@end table - -Network options: - -@table @option - -@item -net nic[,vlan=@var{n}][,macaddr=@var{addr}][,model=@var{type}] -Create a new Network Interface Card and connect it to VLAN @var{n} (@var{n} -= 0 is the default). The NIC is an ne2k_pci by default on the PC -target. Optionally, the MAC address can be changed. If no -@option{-net} option is specified, a single NIC is created. -Qemu can emulate several different models of network card. -Valid values for @var{type} are -@code{i82551}, @code{i82557b}, @code{i82559er}, -@code{ne2k_pci}, @code{ne2k_isa}, @code{pcnet}, @code{rtl8139}, -@code{e1000}, @code{smc91c111}, @code{lance} and @code{mcf_fec}. -Not all devices are supported on all targets. Use -net nic,model=? -for a list of available devices for your target. - -@item -net user[,vlan=@var{n}][,hostname=@var{name}] -Use the user mode network stack which requires no administrator -privilege to run. @option{hostname=name} can be used to specify the client -hostname reported by the builtin DHCP server. - -@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}][,downscript=@var{dfile}] -Connect the host TAP network interface @var{name} to VLAN @var{n}, use -the network script @var{file} to configure it and the network script -@var{dfile} to deconfigure it. If @var{name} is not provided, the OS -automatically provides one. @option{fd}=@var{h} can be used to specify -the handle of an already opened host TAP interface. The default network -configure script is @file{/etc/qemu-ifup} and the default network -deconfigure script is @file{/etc/qemu-ifdown}. Use @option{script=no} -or @option{downscript=no} to disable script execution. Example: - -@example -qemu linux.img -net nic -net tap -@end example - -More complicated example (two NICs, each one connected to a TAP device) -@example -qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ - -net nic,vlan=1 -net tap,vlan=1,ifname=tap1 -@end example - - -@item -net socket[,vlan=@var{n}][,fd=@var{h}][,listen=[@var{host}]:@var{port}][,connect=@var{host}:@var{port}] - -Connect the VLAN @var{n} to a remote VLAN in another QEMU virtual -machine using a TCP socket connection. If @option{listen} is -specified, QEMU waits for incoming connections on @var{port} -(@var{host} is optional). @option{connect} is used to connect to -another QEMU instance using the @option{listen} option. @option{fd}=@var{h} -specifies an already opened TCP socket. - -Example: -@example -# launch a first QEMU instance -qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \ - -net socket,listen=:1234 -# connect the VLAN 0 of this instance to the VLAN 0 -# of the first instance -qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \ - -net socket,connect=127.0.0.1:1234 -@end example - -@item -net socket[,vlan=@var{n}][,fd=@var{h}][,mcast=@var{maddr}:@var{port}] - -Create a VLAN @var{n} shared with another QEMU virtual -machines using a UDP multicast socket, effectively making a bus for -every QEMU with same multicast address @var{maddr} and @var{port}. -NOTES: -@enumerate -@item -Several QEMU can be running on different hosts and share same bus (assuming -correct multicast setup for these hosts). -@item -mcast support is compatible with User Mode Linux (argument @option{eth@var{N}=mcast}), see -@url{http://user-mode-linux.sf.net}. -@item -Use @option{fd=h} to specify an already opened UDP multicast socket. -@end enumerate - -Example: -@example -# launch one QEMU instance -qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \ - -net socket,mcast=230.0.0.1:1234 -# launch another QEMU instance on same "bus" -qemu linux.img -net nic,macaddr=52:54:00:12:34:57 \ - -net socket,mcast=230.0.0.1:1234 -# launch yet another QEMU instance on same "bus" -qemu linux.img -net nic,macaddr=52:54:00:12:34:58 \ - -net socket,mcast=230.0.0.1:1234 -@end example - -Example (User Mode Linux compat.): -@example -# launch QEMU instance (note mcast address selected -# is UML's default) -qemu linux.img -net nic,macaddr=52:54:00:12:34:56 \ - -net socket,mcast=239.192.168.1:1102 -# launch UML -/path/to/linux ubd0=/path/to/root_fs eth0=mcast -@end example - -@item -net vde[,vlan=@var{n}][,sock=@var{socketpath}][,port=@var{n}][,group=@var{groupname}][,mode=@var{octalmode}] -Connect VLAN @var{n} to PORT @var{n} of a vde switch running on host and -listening for incoming connections on @var{socketpath}. Use GROUP @var{groupname} -and MODE @var{octalmode} to change default ownership and permissions for -communication port. This option is available only if QEMU has been compiled -with vde support enabled. - -Example: -@example -# launch vde switch -vde_switch -F -sock /tmp/myswitch -# launch QEMU instance -qemu linux.img -net nic -net vde,sock=/tmp/myswitch -@end example - -@item -net none -Indicate that no network devices should be configured. It is used to -override the default configuration (@option{-net nic -net user}) which -is activated if no @option{-net} options are provided. - -@item -tftp @var{dir} -When using the user mode network stack, activate a built-in TFTP -server. The files in @var{dir} will be exposed as the root of a TFTP server. -The TFTP client on the guest must be configured in binary mode (use the command -@code{bin} of the Unix TFTP client). The host IP address on the guest is as -usual 10.0.2.2. - -@item -bootp @var{file} -When using the user mode network stack, broadcast @var{file} as the BOOTP -filename. In conjunction with @option{-tftp}, this can be used to network boot -a guest from a local directory. - -Example (using pxelinux): -@example -qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0 -@end example - -@item -smb @var{dir} -When using the user mode network stack, activate a built-in SMB -server so that Windows OSes can access to the host files in @file{@var{dir}} -transparently. - -In the guest Windows OS, the line: -@example -10.0.2.4 smbserver -@end example -must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) -or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). - -Then @file{@var{dir}} can be accessed in @file{\\smbserver\qemu}. - -Note that a SAMBA server must be installed on the host OS in -@file{/usr/sbin/smbd}. QEMU was tested successfully with smbd version -2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3. - -@item -redir [tcp|udp]:@var{host-port}:[@var{guest-host}]:@var{guest-port} - -When using the user mode network stack, redirect incoming TCP or UDP -connections to the host port @var{host-port} to the guest -@var{guest-host} on guest port @var{guest-port}. If @var{guest-host} -is not specified, its value is 10.0.2.15 (default address given by the -built-in DHCP server). - -For example, to redirect host X11 connection from screen 1 to guest -screen 0, use the following: - -@example -# on the host -qemu -redir tcp:6001::6000 [...] -# this host xterm should open in the guest X11 server -xterm -display :1 -@end example - -To redirect telnet connections from host port 5555 to telnet port on -the guest, use the following: - -@example -# on the host -qemu -redir tcp:5555::23 [...] -telnet localhost 5555 -@end example - -Then when you use on the host @code{telnet localhost 5555}, you -connect to the guest telnet server. - -@end table - -Bluetooth(R) options: -@table @option - -@item -bt hci[...] -Defines the function of the corresponding Bluetooth HCI. -bt options -are matched with the HCIs present in the chosen machine type. For -example when emulating a machine with only one HCI built into it, only -the first @code{-bt hci[...]} option is valid and defines the HCI's -logic. The Transport Layer is decided by the machine type. Currently -the machines @code{n800} and @code{n810} have one HCI and all other -machines have none. - -@anchor{bt-hcis} -The following three types are recognized: - -@table @code -@item -bt hci,null -(default) The corresponding Bluetooth HCI assumes no internal logic -and will not respond to any HCI commands or emit events. - -@item -bt hci,host[:@var{id}] -(@code{bluez} only) The corresponding HCI passes commands / events -to / from the physical HCI identified by the name @var{id} (default: -@code{hci0}) on the computer running QEMU. Only available on @code{bluez} -capable systems like Linux. - -@item -bt hci[,vlan=@var{n}] -Add a virtual, standard HCI that will participate in the Bluetooth -scatternet @var{n} (default @code{0}). Similarly to @option{-net} -VLANs, devices inside a bluetooth network @var{n} can only communicate -with other devices in the same network (scatternet). -@end table - -@item -bt vhci[,vlan=@var{n}] -(Linux-host only) Create a HCI in scatternet @var{n} (default 0) attached -to the host bluetooth stack instead of to the emulated target. This -allows the host and target machines to participate in a common scatternet -and communicate. Requires the Linux @code{vhci} driver installed. Can -be used as following: - -@example -qemu [...OPTIONS...] -bt hci,vlan=5 -bt vhci,vlan=5 -@end example - -@item -bt device:@var{dev}[,vlan=@var{n}] -Emulate a bluetooth device @var{dev} and place it in network @var{n} -(default @code{0}). QEMU can only emulate one type of bluetooth devices -currently: - -@table @code -@item keyboard -Virtual wireless keyboard implementing the HIDP bluetooth profile. -@end table - -@end table - -Linux boot specific: When using these options, you can use a given -Linux kernel without installing it in the disk image. It can be useful -for easier testing of various kernels. - -@table @option - -@item -kernel @var{bzImage} -Use @var{bzImage} as kernel image. - -@item -append @var{cmdline} -Use @var{cmdline} as kernel command line - -@item -initrd @var{file} -Use @var{file} as initial ram disk. - -@end table - -Debug/Expert options: -@table @option - -@item -serial @var{dev} -Redirect the virtual serial port to host character device -@var{dev}. The default device is @code{vc} in graphical mode and -@code{stdio} in non graphical mode. - -This option can be used several times to simulate up to 4 serials -ports. - -Use @code{-serial none} to disable all serial ports. - -Available character devices are: -@table @code -@item vc[:WxH] -Virtual console. Optionally, a width and height can be given in pixel with -@example -vc:800x600 -@end example -It is also possible to specify width or height in characters: -@example -vc:80Cx24C -@end example -@item pty -[Linux only] Pseudo TTY (a new PTY is automatically allocated) -@item none -No device is allocated. -@item null -void device -@item /dev/XXX -[Linux only] Use host tty, e.g. @file{/dev/ttyS0}. The host serial port -parameters are set according to the emulated ones. -@item /dev/parport@var{N} -[Linux only, parallel port only] Use host parallel port -@var{N}. Currently SPP and EPP parallel port features can be used. -@item file:@var{filename} -Write output to @var{filename}. No character can be read. -@item stdio -[Unix only] standard input/output -@item pipe:@var{filename} -name pipe @var{filename} -@item COM@var{n} -[Windows only] Use host serial port @var{n} -@item udp:[@var{remote_host}]:@var{remote_port}[@@[@var{src_ip}]:@var{src_port}] -This implements UDP Net Console. -When @var{remote_host} or @var{src_ip} are not specified -they default to @code{0.0.0.0}. -When not using a specified @var{src_port} a random port is automatically chosen. - -If you just want a simple readonly console you can use @code{netcat} or -@code{nc}, by starting qemu with: @code{-serial udp::4555} and nc as: -@code{nc -u -l -p 4555}. Any time qemu writes something to that port it -will appear in the netconsole session. - -If you plan to send characters back via netconsole or you want to stop -and start qemu a lot of times, you should have qemu use the same -source port each time by using something like @code{-serial -udp::4555@@:4556} to qemu. Another approach is to use a patched -version of netcat which can listen to a TCP port and send and receive -characters via udp. If you have a patched version of netcat which -activates telnet remote echo and single char transfer, then you can -use the following options to step up a netcat redirector to allow -telnet on port 5555 to access the qemu port. -@table @code -@item Qemu Options: --serial udp::4555@@:4556 -@item netcat options: --u -P 4555 -L 0.0.0.0:4556 -t -p 5555 -I -T -@item telnet options: -localhost 5555 -@end table - - -@item tcp:[@var{host}]:@var{port}[,@var{server}][,nowait][,nodelay] -The TCP Net Console has two modes of operation. It can send the serial -I/O to a location or wait for a connection from a location. By default -the TCP Net Console is sent to @var{host} at the @var{port}. If you use -the @var{server} option QEMU will wait for a client socket application -to connect to the port before continuing, unless the @code{nowait} -option was specified. The @code{nodelay} option disables the Nagle buffering -algorithm. If @var{host} is omitted, 0.0.0.0 is assumed. Only -one TCP connection at a time is accepted. You can use @code{telnet} to -connect to the corresponding character device. -@table @code -@item Example to send tcp console to 192.168.0.2 port 4444 --serial tcp:192.168.0.2:4444 -@item Example to listen and wait on port 4444 for connection --serial tcp::4444,server -@item Example to not wait and listen on ip 192.168.0.100 port 4444 --serial tcp:192.168.0.100:4444,server,nowait -@end table - -@item telnet:@var{host}:@var{port}[,server][,nowait][,nodelay] -The telnet protocol is used instead of raw tcp sockets. The options -work the same as if you had specified @code{-serial tcp}. The -difference is that the port acts like a telnet server or client using -telnet option negotiation. This will also allow you to send the -MAGIC_SYSRQ sequence if you use a telnet that supports sending the break -sequence. Typically in unix telnet you do it with Control-] and then -type "send break" followed by pressing the enter key. - -@item unix:@var{path}[,server][,nowait] -A unix domain socket is used instead of a tcp socket. The option works the -same as if you had specified @code{-serial tcp} except the unix domain socket -@var{path} is used for connections. - -@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. -@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 - -@item braille -Braille device. This will use BrlAPI to display the braille output on a real -or fake device. - -@end table - -@item -parallel @var{dev} -Redirect the virtual parallel port to host device @var{dev} (same -devices as the serial port). On Linux hosts, @file{/dev/parportN} can -be used to use hardware devices connected on the corresponding host -parallel port. - -This option can be used several times to simulate up to 3 parallel -ports. - -Use @code{-parallel none} to disable all parallel ports. - -@item -monitor @var{dev} -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. - -@item -echr numeric_ascii_value -Change the escape character used for switching to the monitor when using -monitor and serial sharing. The default is @code{0x01} when using the -@code{-nographic} option. @code{0x01} is equal to pressing -@code{Control-a}. You can select a different character from the ascii -control keys where 1 through 26 map to Control-a through Control-z. For -instance you could use the either of the following to change the escape -character to Control-t. -@table @code -@item -echr 0x14 -@item -echr 20 -@end table - -@item -s -Wait gdb connection to port 1234 (@pxref{gdb_usage}). -@item -p @var{port} -Change gdb connection port. @var{port} can be either a decimal number -to specify a TCP port, or a host device (same devices as the serial port). -@item -S -Do not start CPU at startup (you must type 'c' in the monitor). -@item -d -Output log in /tmp/qemu.log -@item -hdachs @var{c},@var{h},@var{s},[,@var{t}] -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. - -@item -L path -Set the directory for the BIOS, VGA BIOS and keymaps. - -@item -vga @var{type} -Select type of VGA card to emulate. Valid values for @var{type} are -@table @code -@item cirrus -Cirrus Logic GD5446 Video card. All Windows versions starting from -Windows 95 should recognize and use this graphic card. For optimal -performances, use 16 bit color depth in the guest and the host OS. -(This one is the default) -@item std -Standard VGA card with Bochs VBE extensions. If your guest OS -supports the VESA 2.0 VBE extensions (e.g. Windows XP) and if you want -to use high resolution modes (>= 1280x1024x16) then you should use -this option. -@item vmware -VMWare SVGA-II compatible adapter. Use it if you have sufficiently -recent XFree86/XOrg server or Windows guest with a driver for this -card. -@end table - -@item -no-acpi -Disable ACPI (Advanced Configuration and Power Interface) support. Use -it if your guest OS complains about ACPI problems (PC target machine -only). - -@item -no-reboot -Exit instead of rebooting. - -@item -no-shutdown -Don't exit QEMU on guest shutdown, but instead only stop the emulation. -This allows for instance switching to monitor to commit changes to the -disk image. - -@item -loadvm file -Start right away with a saved state (@code{loadvm} in monitor) - -@item -semihosting -Enable semihosting syscall emulation (ARM and M68K target machines only). - -On ARM this implements the "Angel" interface. -On M68K this implements the "ColdFire GDB" interface used by libgloss. - -Note that this allows guest direct access to the host filesystem, -so should only be used with trusted guest OS. - -@item -icount [N|auto] -Enable virtual instruction counter. The virtual cpu will execute one -instruction every 2^N ns of virtual time. If @code{auto} is specified -then the virtual cpu speed will be automatically adjusted to keep virtual -time within a few seconds of real time. - -Note that while this option can give deterministic behavior, it does not -provide cycle accurate emulation. Modern CPUs contain superscalar out of -order cores with complex cache hierarchies. The number of instructions -executed often has little or no correlation with actual performance. -@end table +@include qemu-options.texi @c man end @@ -1132,13 +264,14 @@ During emulation, if you are using the @option{-nographic} option, use @table @key @item Ctrl-a h +@item Ctrl-a ? Print this help @item Ctrl-a x Exit emulator @item Ctrl-a s Save disk data back to file (if -snapshot) @item Ctrl-a t -toggle console timestamps +Toggle console timestamps @item Ctrl-a b Send break (magic sysrq in Linux) @item Ctrl-a c @@ -1185,238 +318,7 @@ from a disk file. The following commands are available: -@table @option - -@item help or ? [@var{cmd}] -Show the help for all commands or just for command @var{cmd}. - -@item commit -Commit changes to the disk images (if -snapshot is used). - -@item info @var{subcommand} -Show various information about the system state. - -@table @option -@item info network -show the various VLANs and the associated devices -@item info block -show the block devices -@item info registers -show the cpu registers -@item info history -show the command line history -@item info pci -show emulated PCI device -@item info usb -show USB devices plugged on the virtual USB hub -@item info usbhost -show all USB host devices -@item info capture -show information about active capturing -@item info snapshots -show list of VM snapshots -@item info mice -show which guest mouse is receiving events -@end table - -@item q or quit -Quit the emulator. - -@item eject [-f] @var{device} -Eject a removable medium (use -f to force it). - -@item change @var{device} @var{setting} - -Change the configuration of a device. - -@table @option -@item change @var{diskdevice} @var{filename} -Change the medium for a removable disk device to point to @var{filename}. eg - -@example -(qemu) change ide1-cd0 /path/to/some.iso -@end example - -@item change vnc @var{display},@var{options} -Change the configuration of the VNC server. The valid syntax for @var{display} -and @var{options} are described at @ref{sec_invocation}. eg - -@example -(qemu) change vnc localhost:1 -@end example - -@item change vnc password [@var{password}] - -Change the password associated with the VNC server. If the new password is not -supplied, the monitor will prompt for it to be entered. VNC passwords are only -significant up to 8 letters. eg - -@example -(qemu) change vnc password -Password: ******** -@end example - -@end table - -@item screendump @var{filename} -Save screen into PPM image @var{filename}. - -@item mouse_move @var{dx} @var{dy} [@var{dz}] -Move the active mouse to the specified coordinates @var{dx} @var{dy} -with optional scroll axis @var{dz}. - -@item mouse_button @var{val} -Change the active mouse button state @var{val} (1=L, 2=M, 4=R). - -@item mouse_set @var{index} -Set which mouse device receives events at given @var{index}, index -can be obtained with -@example -info mice -@end example - -@item wavcapture @var{filename} [@var{frequency} [@var{bits} [@var{channels}]]] -Capture audio into @var{filename}. Using sample rate @var{frequency} -bits per sample @var{bits} and number of channels @var{channels}. - -Defaults: -@itemize @minus -@item Sample rate = 44100 Hz - CD quality -@item Bits = 16 -@item Number of channels = 2 - Stereo -@end itemize - -@item stopcapture @var{index} -Stop capture with a given @var{index}, index can be obtained with -@example -info capture -@end example - -@item log @var{item1}[,...] -Activate logging of the specified items to @file{/tmp/qemu.log}. - -@item savevm [@var{tag}|@var{id}] -Create a snapshot of the whole virtual machine. If @var{tag} is -provided, it is used as human readable identifier. If there is already -a snapshot with the same tag or ID, it is replaced. More info at -@ref{vm_snapshots}. - -@item loadvm @var{tag}|@var{id} -Set the whole virtual machine to the snapshot identified by the tag -@var{tag} or the unique snapshot ID @var{id}. - -@item delvm @var{tag}|@var{id} -Delete the snapshot identified by @var{tag} or @var{id}. - -@item stop -Stop emulation. - -@item c or cont -Resume emulation. - -@item gdbserver [@var{port}] -Start gdbserver session (default @var{port}=1234) - -@item x/fmt @var{addr} -Virtual memory dump starting at @var{addr}. - -@item xp /@var{fmt} @var{addr} -Physical memory dump starting at @var{addr}. - -@var{fmt} is a format which tells the command how to format the -data. Its syntax is: @option{/@{count@}@{format@}@{size@}} - -@table @var -@item count -is the number of items to be dumped. - -@item format -can be x (hex), d (signed decimal), u (unsigned decimal), o (octal), -c (char) or i (asm instruction). - -@item size -can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, -@code{h} or @code{w} can be specified with the @code{i} format to -respectively select 16 or 32 bit code instruction size. - -@end table - -Examples: -@itemize -@item -Dump 10 instructions at the current instruction pointer: -@example -(qemu) x/10i $eip -0x90107063: ret -0x90107064: sti -0x90107065: lea 0x0(%esi,1),%esi -0x90107069: lea 0x0(%edi,1),%edi -0x90107070: ret -0x90107071: jmp 0x90107080 -0x90107073: nop -0x90107074: nop -0x90107075: nop -0x90107076: nop -@end example - -@item -Dump 80 16 bit values at the start of the video memory. -@smallexample -(qemu) xp/80hx 0xb8000 -0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42 -0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41 -0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72 -0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73 -0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20 -0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720 -0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 -0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 -0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 -0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 -@end smallexample -@end itemize - -@item p or print/@var{fmt} @var{expr} - -Print expression value. Only the @var{format} part of @var{fmt} is -used. - -@item sendkey @var{keys} - -Send @var{keys} to the emulator. @var{keys} could be the name of the -key or @code{#} followed by the raw value in either decimal or hexadecimal -format. Use @code{-} to press several keys simultaneously. Example: -@example -sendkey ctrl-alt-f1 -@end example - -This command is useful to send keys that your graphical user interface -intercepts at low level, such as @code{ctrl-alt-f1} in X Window. - -@item system_reset - -Reset the system. - -@item boot_set @var{bootdevicelist} - -Define new values for the boot device list. Those values will override -the values specified on the command line through the @code{-boot} option. - -The values that can be specified here depend on the machine type, but are -the same that can be specified in the @code{-boot} command line option. - -@item usb_add @var{devname} - -Add the USB device @var{devname}. For details of available devices see -@ref{usb_devices} - -@item usb_del @var{devname} - -Remove the USB device @var{devname} from the QEMU virtual USB -hub. @var{devname} has the syntax @code{bus.addr}. Use the monitor -command @code{info usb} to see the devices you can remove. - -@end table +@include qemu-monitor.texi @subsection Integer expressions @@ -1907,7 +809,10 @@ considerations depending on the deployment scenarios. * vnc_sec_certificate:: * vnc_sec_certificate_verify:: * vnc_sec_certificate_pw:: +* vnc_sec_sasl:: +* vnc_sec_certificate_sasl:: * vnc_generate_cert:: +* vnc_setup_sasl:: @end menu @node vnc_sec_none @subsection Without passwords @@ -1990,6 +895,41 @@ Password: ******** (qemu) @end example + +@node vnc_sec_sasl +@subsection With SASL authentication + +The SASL authentication method is a VNC extension, that provides an +easily extendable, pluggable authentication method. This allows for +integration with a wide range of authentication mechanisms, such as +PAM, GSSAPI/Kerberos, LDAP, SQL databases, one-time keys and more. +The strength of the authentication depends on the exact mechanism +configured. If the chosen mechanism also provides a SSF layer, then +it will encrypt the datastream as well. + +Refer to the later docs on how to choose the exact SASL mechanism +used for authentication, but assuming use of one supporting SSF, +then QEMU can be launched with: + +@example +qemu [...OPTIONS...] -vnc :1,sasl -monitor stdio +@end example + +@node vnc_sec_certificate_sasl +@subsection With x509 certificates and SASL authentication + +If the desired SASL authentication mechanism does not supported +SSF layers, then it is strongly advised to run it in combination +with TLS and x509 certificates. This provides securely encrypted +data stream, avoiding risk of compromising of the security +credentials. This can be enabled, by combining the 'sasl' option +with the aforementioned TLS + x509 options: + +@example +qemu [...OPTIONS...] -vnc :1,tls,x509,sasl -monitor stdio +@end example + + @node vnc_generate_cert @subsection Generating certificates for VNC @@ -2101,6 +1041,50 @@ EOF The @code{client-key.pem} and @code{client-cert.pem} files should now be securely copied to the client for which they were generated. + +@node vnc_setup_sasl + +@subsection Configuring SASL mechanisms + +The following documentation assumes use of the Cyrus SASL implementation on a +Linux host, but the principals should apply to any other SASL impl. When SASL +is enabled, the mechanism configuration will be loaded from system default +SASL service config /etc/sasl2/qemu.conf. If running QEMU as an +unprivileged user, an environment variable SASL_CONF_PATH can be used +to make it search alternate locations for the service config. + +The default configuration might contain + +@example +mech_list: digest-md5 +sasldb_path: /etc/qemu/passwd.db +@end example + +This says to use the 'Digest MD5' mechanism, which is similar to the HTTP +Digest-MD5 mechanism. The list of valid usernames & passwords is maintained +in the /etc/qemu/passwd.db file, and can be updated using the saslpasswd2 +command. While this mechanism is easy to configure and use, it is not +considered secure by modern standards, so only suitable for developers / +ad-hoc testing. + +A more serious deployment might use Kerberos, which is done with the 'gssapi' +mechanism + +@example +mech_list: gssapi +keytab: /etc/qemu/krb5.tab +@end example + +For this to work the administrator of your KDC must generate a Kerberos +principal for the server, with a name of 'qemu/somehost.example.com@@EXAMPLE.COM' +replacing 'somehost.example.com' with the fully qualified host name of the +machine running QEMU, and 'EXAMPLE.COM' with the Keberos Realm. + +Other configurations will be left as an exercise for the reader. It should +be noted that only Digest-MD5 and GSSAPI provides a SSF layer for data +encryption. For all other mechanisms, VNC should always be configured to +use TLS and x509 certificates to protect security credentials from snooping. + @node gdb_usage @section GDB usage @@ -2293,7 +1277,7 @@ QEMU emulates the following PowerMac peripherals: @itemize @minus @item -UniNorth PCI Bridge +UniNorth or Grackle PCI Bridge @item PCI VGA compatible card with VESA Bochs Extensions @item @@ -2331,9 +1315,9 @@ QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at @url{http://perso.magic.fr/l_indien/OpenHackWare/index.htm}. Since version 0.9.1, QEMU uses OpenBIOS @url{http://www.openbios.org/} -for the g3bw PowerMac machine. OpenBIOS is a free (GPL v2) portable -firmware implementation. The goal is to implement a 100% IEEE -1275-1994 (referred to as Open Firmware) compliant firmware. +for the g3beige and mac99 PowerMac machines. OpenBIOS is a free (GPL +v2) portable firmware implementation. The goal is to implement a 100% +IEEE 1275-1994 (referred to as Open Firmware) compliant firmware. @c man begin OPTIONS @@ -2558,11 +1542,11 @@ PIIX4 PCI/USB/SMbus controller @item The Multi-I/O chip's serial device @item -PCnet32 PCI network card +PCI network cards (PCnet32 and others) @item Malta FPGA serial device @item -Cirrus VGA graphics card +Cirrus (default) or any other PCI VGA graphics card @end itemize The ACER Pica emulation supports: @@ -2841,9 +1825,47 @@ Secure Digital card connected to OMAP MMC/SD host Three on-chip UARTs @end itemize +The "Syborg" Symbian Virtual Platform base model includes the following +elements: + +@itemize @minus +@item +ARM Cortex-A8 CPU +@item +Interrupt controller +@item +Timer +@item +Real Time Clock +@item +Keyboard +@item +Framebuffer +@item +Touchscreen +@item +UARTs +@end itemize + A Linux 2.6 test image is available on the QEMU web site. More information is available in the QEMU mailing-list archive. +@c man begin OPTIONS + +The following options are specific to the ARM emulation: + +@table @option + +@item -semihosting +Enable semihosting syscall emulation. + +On ARM this implements the "Angel" interface. + +Note that this allows guest direct access to the host filesystem, +so should only be used with trusted guest OS. + +@end table + @node ColdFire System emulator @section ColdFire System emulator @@ -2870,6 +1892,22 @@ MCF5206 ColdFire V2 Microprocessor. Two on-chip UARTs. @end itemize +@c man begin OPTIONS + +The following options are specific to the ARM emulation: + +@table @option + +@item -semihosting +Enable semihosting syscall emulation. + +On M68K this implements the "ColdFire GDB" interface used by libgloss. + +Note that this allows guest direct access to the host filesystem, +so should only be used with trusted guest OS. + +@end table + @node QEMU User space emulator @chapter QEMU User space emulator @@ -3011,6 +2049,8 @@ Activate log (logfile=/tmp/qemu.log) Act as if the host page size was 'pagesize' bytes @item -g port Wait gdb connection to port +@item -singlestep +Run the emulation in single step mode. @end table Environment variables: @@ -3129,6 +2169,8 @@ Debug options: Activate log (logfile=/tmp/qemu.log) @item -p pagesize Act as if the host page size was 'pagesize' bytes +@item -singlestep +Run the emulation in single step mode. @end table @node BSD User space emulator @@ -3191,6 +2233,8 @@ Debug options: Activate log (logfile=/tmp/qemu.log) @item -p pagesize Act as if the host page size was 'pagesize' bytes +@item -singlestep +Run the emulation in single step mode. @end table @node compilation @@ -3227,16 +2271,6 @@ make install @end example to install QEMU in @file{/usr/local}. -@subsection GCC version - -In order to compile QEMU successfully, it is very important that you -have the right tools. The most important one is gcc. On most hosts and -in particular on x86 ones, @emph{gcc 4.x is not supported}. If your -Linux distribution includes a gcc 4.x compiler, you can usually -install an older version (it is invoked by @code{gcc32} or -@code{gcc34}). The QEMU configure script automatically probes for -these older versions so that usually you don't have to do anything. - @node Windows @section Windows