X-Git-Url: https://repo.jachan.dev/qemu.git/blobdiff_plain/7e049b8a19e934a8b4a8807d5d2452e0749eac6c..91834991f6bc7aafe8c0ed9b54c2716b60e61deb:/qemu-doc.texi diff --git a/qemu-doc.texi b/qemu-doc.texi index cb05aa58cc..1f409f47f4 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -50,13 +50,13 @@ QEMU has two operating modes: @itemize @minus -@item +@item Full system emulation. In this mode, QEMU emulates a full system (for example a PC), including one or several processors and various peripherals. It can be used to launch different Operating Systems without rebooting the PC or to debug system code. -@item +@item User mode emulation. In this mode, QEMU can launch processes compiled for one CPU on another CPU. It can be used to launch the Wine Windows API emulator (@url{http://www.winehq.org}) or @@ -65,7 +65,7 @@ to ease cross-compilation and cross-debugging. @end itemize QEMU can run without an host kernel driver and yet gives acceptable -performance. +performance. For system emulation, the following hardware targets are supported: @itemize @@ -74,17 +74,22 @@ For system emulation, the following hardware targets are supported: @item PREP (PowerPC processor) @item G3 BW PowerMac (PowerPC processor) @item Mac99 PowerMac (PowerPC processor, in progress) -@item Sun4m (32-bit Sparc processor) +@item Sun4m/Sun4c/Sun4d (32-bit Sparc processor) @item Sun4u (64-bit Sparc processor, in progress) -@item Malta board (32-bit MIPS processor) -@item ARM Integrator/CP (ARM926E, 1026E or 946E processor) -@item ARM Versatile baseboard (ARM926E) -@item ARM RealView Emulation baseboard (ARM926EJ-S) +@item Malta board (32-bit and 64-bit MIPS processors) +@item MIPS Magnum (64-bit MIPS processor) +@item ARM Integrator/CP (ARM) +@item ARM Versatile baseboard (ARM) +@item ARM RealView Emulation baseboard (ARM) @item Spitz, Akita, Borzoi and Terrier PDAs (PXA270 processor) +@item Luminary Micro LM3S811EVB (ARM Cortex-M3) +@item Luminary Micro LM3S6965EVB (ARM Cortex-M3) +@item Freescale MCF5208EVB (ColdFire V2). @item Arnewsh MCF5206 evaluation board (ColdFire V2). +@item Palm Tungsten|E PDA (OMAP310 processor) @end itemize -For user emulation, x86, PowerPC, ARM, MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported. +For user emulation, x86, PowerPC, ARM, 32-bit MIPS, Sparc32/64 and ColdFire(m68k) CPUs are supported. @node Installation @chapter Installation @@ -128,6 +133,7 @@ Download the experimental binary installer at * pcsys_network:: Network emulation * direct_linux_boot:: Direct Linux Boot * pcsys_usb:: USB emulation +* vnc_security:: VNC security * gdb_usage:: GDB usage * pcsys_os_specific:: Target OS specific information @end menu @@ -141,18 +147,18 @@ The QEMU PC System emulator simulates the following peripherals: @itemize @minus -@item +@item i440FX host PCI bridge and PIIX3 PCI to ISA bridge @item Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA extensions (hardware level, including all non standard modes). @item PS/2 mouse and keyboard -@item +@item 2 PCI IDE interfaces with hard disk and CD-ROM support @item Floppy disk -@item +@item PCI/ISA PCI network adapters @item Serial ports @@ -161,21 +167,28 @@ Creative SoundBlaster 16 sound card @item ENSONIQ AudioPCI ES1370 sound card @item +Intel 82801AA AC97 Audio compatible sound card +@item Adlib(OPL2) - Yamaha YM3812 compatible chip @item +Gravis Ultrasound GF1 sound card +@item PCI UHCI USB controller and a virtual USB hub. @end itemize SMP is supported with up to 255 CPUs. -Note that adlib is only available when QEMU was configured with --enable-adlib +Note that adlib, ac97 and gus are only available when QEMU was configured +with --enable-adlib, --enable-ac97 or --enable-gus respectively. QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL VGA BIOS. QEMU uses YM3812 emulation by Tatsuyuki Satoh. +QEMU uses GUS emulation(GUSEMU32 @url{http://www.deinmeister.de/gusemu/}) +by Tibor "TS" Schütz. + @c man end @node pcsys_quickstart @@ -194,7 +207,7 @@ Linux should boot and give you a prompt. @example @c man begin SYNOPSIS -usage: qemu [options] [disk_image] +usage: qemu [options] [@var{disk_image}] @c man end @end example @@ -203,25 +216,102 @@ usage: qemu [options] [disk_image] General options: @table @option -@item -M machine -Select the emulated machine (@code{-M ?} for list) +@item -M @var{machine} +Select the emulated @var{machine} (@code{-M ?} for list) -@item -fda file -@item -fdb file +@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 file -@item -hdb file -@item -hdc file -@item -hdd file +@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 file -Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and +@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. +@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 "on" or "off" and allows to disable host cache to access 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. +@end table + +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. @@ -235,12 +325,79 @@ the write back by pressing @key{C-a s} (@pxref{disk_images}). Disable boot signature checking for floppy disks in Bochs BIOS. It may be needed to boot from old floppy disks. -@item -m megs -Set virtual RAM size to @var{megs} megabytes. Default is 128 MB. +@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 -smp n +@item -smp @var{n} Simulate an SMP system with @var{n} CPUs. On the PC target, up to 255 -CPUs are supported. +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 hda +qemu -soundhw es1370 hda +qemu -soundhw ac97 hda +qemu -soundhw all hda +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 format 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 display in the SDL window caption. +The @var{name} will also be used for the VNC server. + +@end table + +Display options: +@table @option @item -nographic @@ -250,29 +407,105 @@ 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 -vnc display +@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} -option to set the keyboard layout if you are not using en-us. +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} -@var{display} may be in the form @var{interface:d}, in which case connections -will only be allowed from @var{interface} on display @var{d}. Optionally, -@var{interface} can be omitted. @var{display} can also be in the form -@var{unix:path} where @var{path} is the location of a unix socket to listen for -connections on. +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} -@item -k language +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 @@ -289,71 +522,53 @@ de en-us fi fr-be hr it lv nl-be pt sl tr The default is @code{en-us}. -@item -audio-help +@end table -Will show the audio subsystem help: list of drivers, tunable -parameters. +USB options: +@table @option -@item -soundhw card1,card2,... or -soundhw all +@item -usb +Enable the USB driver (will be the default soon) -Enable audio and selected sound hardware. Use ? to print all -available sound hardware. +@item -usbdevice @var{devname} +Add the USB device @var{devname}. @xref{usb_devices}. -@example -qemu -soundhw sb16,adlib hda -qemu -soundhw es1370 hda -qemu -soundhw all hda -qemu -soundhw ? -@end example +@table @code -@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 mouse +Virtual Mouse. This will override the PS/2 mouse emulation when activated. -@item -full-screen -Start in full screen. +@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 -pidfile file -Store the QEMU process PID in @var{file}. It is useful if you launch QEMU -from a script. +@item disk:file +Mass storage device based on file -@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 host:bus.addr +Pass through the host device identified by bus.addr (Linux only). -@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 host:vendor_id:product_id +Pass through the host device identified by vendor_id:product_id (Linux only). -@item -option-rom file -Load the contents of file as an option ROM. This option is useful to load -things like EtherBoot. +@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 -name string -Sets the name of the guest. This name will be display in the SDL window -caption. The name will also be used for the VNC server. +@item braille +Braille device. This will use BrlAPI to display the braille output on a real +or fake device. @end table -USB options: -@table @option - -@item -usb -Enable the USB driver (will be the default soon) - -@item -usbdevice devname -Add the USB device @var{devname}. @xref{usb_devices}. @end table Network options: @table @option -@item -net nic[,vlan=n][,macaddr=addr][,model=type] +@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 @@ -362,21 +577,21 @@ 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{smc91c111}, @code{lance} and @code{mcf_fec}. +@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=n][,hostname=name] +@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=n][,fd=h][,ifname=name][,script=file] +@item -net tap[,vlan=@var{n}][,fd=@var{h}][,ifname=@var{name}][,script=@var{file}] Connect the host TAP network interface @var{name} to VLAN @var{n} and use the network script @var{file} to configure it. The default network script is @file{/etc/qemu-ifup}. Use @option{script=no} to disable script execution. If @var{name} is not -provided, the OS automatically provides one. @option{fd=h} can be +provided, the OS automatically provides one. @option{fd}=@var{h} can be used to specify the handle of an already opened host TAP interface. Example: @example @@ -390,13 +605,13 @@ qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \ @end example -@item -net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port] +@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=h} +another QEMU instance using the @option{listen} option. @option{fd}=@var{h} specifies an already opened TCP socket. Example: @@ -410,15 +625,15 @@ 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=n][,fd=h][,mcast=maddr:port] +@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 +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 +@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 @@ -455,14 +670,14 @@ 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 dir +@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 file +@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. @@ -472,9 +687,9 @@ Example (using pxelinux): qemu -hda linux.img -boot n -tftp /path/to/tftp/files -bootp /pxelinux.0 @end example -@item -smb dir +@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{dir} +server so that Windows OSes can access to the host files in @file{@var{dir}} transparently. In the guest Windows OS, the line: @@ -484,13 +699,13 @@ In the guest Windows OS, the line: 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{dir} can be accessed in @file{\\smbserver\qemu}. +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]:host-port:[guest-host]:guest-port +@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 @@ -528,13 +743,13 @@ for easier testing of various kernels. @table @option -@item -kernel bzImage +@item -kernel @var{bzImage} Use @var{bzImage} as kernel image. -@item -append cmdline +@item -append @var{cmdline} Use @var{cmdline} as kernel command line -@item -initrd file +@item -initrd @var{file} Use @var{file} as initial ram disk. @end table @@ -542,7 +757,7 @@ Use @var{file} as initial ram disk. Debug/Expert options: @table @option -@item -serial dev +@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. @@ -554,8 +769,15 @@ Use @code{-serial none} to disable all serial ports. Available character devices are: @table @code -@item vc -Virtual console +@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 @@ -565,19 +787,22 @@ 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/parportN +@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:filename -Write output to filename. No character can be read. +@item file:@var{filename} +Write output to @var{filename}. No character can be read. @item stdio [Unix only] standard input/output -@item pipe:filename +@item pipe:@var{filename} name pipe @var{filename} -@item COMn +@item COM@var{n} [Windows only] Use host serial port @var{n} -@item udp:[remote_host]:remote_port[@@[src_ip]: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. +@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: @@ -603,7 +828,7 @@ localhost 5555 @end table -@item tcp:[host]:port[,server][,nowait][,nodelay] +@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 @@ -622,7 +847,7 @@ connect to the corresponding character device. -serial tcp:192.168.0.100:4444,server,nowait @end table -@item telnet:host:port[,server][,nowait][,nodelay] +@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 @@ -631,12 +856,12 @@ 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:path[,server][,nowait] +@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:dev_string +@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 @@ -648,9 +873,13 @@ listening on port 4444 would be: @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 dev +@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 @@ -661,7 +890,7 @@ ports. Use @code{-parallel none} to disable all parallel ports. -@item -monitor dev +@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 @@ -681,15 +910,15 @@ character to Control-t. @end table @item -s -Wait gdb connection to port 1234 (@pxref{gdb_usage}). -@item -p port +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 +@item -d Output log in /tmp/qemu.log -@item -hdachs c,h,s,[,t] +@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 @@ -713,6 +942,11 @@ 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) @@ -762,9 +996,9 @@ During emulation, if you are using the @option{-nographic} option, use @table @key @item Ctrl-a h Print this help -@item Ctrl-a x +@item Ctrl-a x Exit emulator -@item Ctrl-a s +@item Ctrl-a s Save disk data back to file (if -snapshot) @item Ctrl-a t toggle console timestamps @@ -800,9 +1034,9 @@ emulator. You can use it to: @item Remove or insert removable media images -(such as CD-ROM or floppies) +(such as CD-ROM or floppies). -@item +@item Freeze/unfreeze the Virtual Machine (VM) and save or restore its state from a disk file. @@ -816,14 +1050,14 @@ The following commands are available: @table @option -@item help or ? [cmd] +@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 commit +Commit changes to the disk images (if -snapshot is used). -@item info subcommand -show various information about the system state +@item info @var{subcommand} +Show various information about the system state. @table @option @item info network @@ -851,30 +1085,60 @@ show which guest mouse is receiving events @item q or quit Quit the emulator. -@item eject [-f] device +@item eject [-f] @var{device} Eject a removable medium (use -f to force it). -@item change device filename -Change a removable medium. +@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 screendump filename +@item change vnc password + +Change the password associated with the VNC server. The monitor will prompt for +the new password to be entered. VNC passwords are only significant upto 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 dx dy [dz] +@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 val +@item mouse_button @var{val} Change the active mouse button state @var{val} (1=L, 2=M, 4=R). -@item mouse_set index +@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 filename [frequency [bits [channels]]] +@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}. @@ -885,26 +1149,26 @@ Defaults: @item Number of channels = 2 - Stereo @end itemize -@item stopcapture index +@item stopcapture @var{index} Stop capture with a given @var{index}, index can be obtained with @example info capture @end example -@item log item1[,...] +@item log @var{item1}[,...] Activate logging of the specified items to @file{/tmp/qemu.log}. -@item savevm [tag|id] +@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 tag|id +@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 tag|id +@item delvm @var{tag}|@var{id} Delete the snapshot identified by @var{tag} or @var{id}. @item stop @@ -913,20 +1177,20 @@ Stop emulation. @item c or cont Resume emulation. -@item gdbserver [port] -Start gdbserver session (default port=1234) +@item gdbserver [@var{port}] +Start gdbserver session (default @var{port}=1234) -@item x/fmt addr +@item x/fmt @var{addr} Virtual memory dump starting at @var{addr}. -@item xp /fmt 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 +@item count is the number of items to be dumped. @item format @@ -940,11 +1204,11 @@ respectively select 16 or 32 bit code instruction size. @end table -Examples: +Examples: @itemize @item Dump 10 instructions at the current instruction pointer: -@example +@example (qemu) x/10i $eip 0x90107063: ret 0x90107064: sti @@ -960,7 +1224,7 @@ Dump 10 instructions at the current instruction pointer: @item Dump 80 16 bit values at the start of the video memory. -@smallexample +@smallexample (qemu) xp/80hx 0xb8000 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41 @@ -975,12 +1239,12 @@ Dump 80 16 bit values at the start of the video memory. @end smallexample @end itemize -@item p or print/fmt expr +@item p or print/@var{fmt} @var{expr} Print expression value. Only the @var{format} part of @var{fmt} is used. -@item sendkey keys +@item sendkey @var{keys} Send @var{keys} to the emulator. Use @code{-} to press several keys simultaneously. Example: @@ -995,12 +1259,12 @@ intercepts at low level, such as @code{ctrl-alt-f1} in X Window. Reset the system. -@item usb_add devname +@item usb_add @var{devname} Add the USB device @var{devname}. For details of available devices see @ref{usb_devices} -@item usb_del devname +@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 @@ -1097,10 +1361,10 @@ but they are deleted as soon as you exit QEMU. VM snapshots currently have the following known limitations: @itemize -@item +@item They cannot cope with removable devices if they are removed or inserted after a snapshot is done. -@item +@item A few device drivers still have incomplete snapshot support so their state is not saved or restored properly (in particular USB). @end itemize @@ -1154,7 +1418,7 @@ Currently there is no specific code to handle removable media, so it is better to use the @code{change} or @code{eject} monitor commands to change or eject media. @item Hard disks -Hard disks can be used with the syntax: @file{\\.\PhysicalDriveN} +Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}} where @var{N} is the drive number (0 is the first hard disk). WARNING: unless you know what you do, it is better to only make @@ -1166,7 +1430,7 @@ modifications are written in a temporary file). @subsubsection Mac OS X -@file{/dev/cdrom} is an alias to the first CDROM. +@file{/dev/cdrom} is an alias to the first CDROM. Currently there is no specific code to handle removable media, so it is better to use the @code{change} or @code{eject} monitor commands to @@ -1178,7 +1442,7 @@ change or eject media. QEMU can automatically create a virtual FAT disk image from a directory tree. In order to use it, just type: -@example +@example qemu linux.img -hdb fat:/my_directory @end example @@ -1188,14 +1452,14 @@ them via SAMBA or NFS. The default access is @emph{read-only}. Floppies can be emulated with the @code{:floppy:} option: -@example +@example qemu linux.img -fda fat:floppy:/my_directory @end example A read/write support is available for testing (beta stage) with the @code{:rw:} option: -@example +@example qemu linux.img -fda fat:floppy:rw:/my_directory @end example @@ -1263,7 +1527,7 @@ network). The virtual network configuration is the following: | (10.0.2.2) | ----> DNS server (10.0.2.3) - | + | ----> SMB server (10.0.2.4) @end example @@ -1342,21 +1606,40 @@ as necessary to connect multiple USB devices. USB devices can be connected with the @option{-usbdevice} commandline option or the @code{usb_add} monitor command. Available devices are: -@table @var -@item @code{mouse} +@table @code +@item mouse Virtual Mouse. This will override the PS/2 mouse emulation when activated. -@item @code{tablet} +@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 @code{disk:file} +@item disk:@var{file} Mass storage device based on @var{file} (@pxref{disk_images}) -@item @code{host:bus.addr} +@item host:@var{bus.addr} Pass through the host device identified by @var{bus.addr} (Linux only) -@item @code{host:vendor_id:product_id} +@item host:@var{vendor_id:product_id} Pass through the host device identified by @var{vendor_id:product_id} (Linux only) +@item wacom-tablet +Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet} +above but it can be used with the tslib library because in addition to touch +coordinates it reports touch pressure. +@item keyboard +Standard USB keyboard. Will override the PS/2 keyboard (if present). +@item serial:[vendorid=@var{vendor_id}][,product_id=@var{product_id}]:@var{dev} +Serial converter. This emulates an FTDI FT232BM chip connected to host character +device @var{dev}. The available character devices are the same as for the +@code{-serial} option. The @code{vendorid} and @code{productid} options can be +used to override the default 0403:6001. For instance, +@example +usb_add serial:productid=FA00:tcp:192.168.0.2:4444 +@end example +will connect to tcp port 4444 of ip 192.168.0.2, and plug that to the virtual +serial converter, faking a Matrix Orbital LCD Display (USB ID 0403:FA00). +@item braille +Braille device. This will use BrlAPI to display the braille output on a real +or fake device. @end table @node host_usb_devices @@ -1367,7 +1650,7 @@ using it. USB devices requiring real time streaming (i.e. USB Video Cameras) are not supported yet. @enumerate -@item If you use an early Linux 2.4 kernel, verify that no Linux driver +@item If you use an early Linux 2.4 kernel, verify that no Linux driver is actually using the USB device. A simple way to do that is simply to disable the corresponding kernel module by renaming it from @file{mydriver.o} to @file{mydriver.o.disabled}. @@ -1384,7 +1667,7 @@ chown -R myuid /proc/bus/usb @end example @item Launch QEMU and do in the monitor: -@example +@example info usbhost Device 1.2, speed 480 Mb/s Class 00: USB device 1234:5678, USB DISK @@ -1393,7 +1676,7 @@ You should see the list of the devices you can use (Never try to use hubs, it won't work). @item Add the device in QEMU by using: -@example +@example usb_add host:1234:5678 @end example @@ -1407,6 +1690,213 @@ plugged. You can use the option @option{-usbdevice} to do the same. When relaunching QEMU, you may have to unplug and plug again the USB device to make it work again (this is a bug). +@node vnc_security +@section VNC security + +The VNC server capability provides access to the graphical console +of the guest VM across the network. This has a number of security +considerations depending on the deployment scenarios. + +@menu +* vnc_sec_none:: +* vnc_sec_password:: +* vnc_sec_certificate:: +* vnc_sec_certificate_verify:: +* vnc_sec_certificate_pw:: +* vnc_generate_cert:: +@end menu +@node vnc_sec_none +@subsection Without passwords + +The simplest VNC server setup does not include any form of authentication. +For this setup it is recommended to restrict it to listen on a UNIX domain +socket only. For example + +@example +qemu [...OPTIONS...] -vnc unix:/home/joebloggs/.qemu-myvm-vnc +@end example + +This ensures that only users on local box with read/write access to that +path can access the VNC server. To securely access the VNC server from a +remote machine, a combination of netcat+ssh can be used to provide a secure +tunnel. + +@node vnc_sec_password +@subsection With passwords + +The VNC protocol has limited support for password based authentication. Since +the protocol limits passwords to 8 characters it should not be considered +to provide high security. The password can be fairly easily brute-forced by +a client making repeat connections. For this reason, a VNC server using password +authentication should be restricted to only listen on the loopback interface +or UNIX domain sockets. Password ayuthentication is requested with the @code{password} +option, and then once QEMU is running the password is set with the monitor. Until +the monitor is used to set the password all clients will be rejected. + +@example +qemu [...OPTIONS...] -vnc :1,password -monitor stdio +(qemu) change vnc password +Password: ******** +(qemu) +@end example + +@node vnc_sec_certificate +@subsection With x509 certificates + +The QEMU VNC server also implements the VeNCrypt extension allowing use of +TLS for encryption of the session, and x509 certificates for authentication. +The use of x509 certificates is strongly recommended, because TLS on its +own is susceptible to man-in-the-middle attacks. Basic x509 certificate +support provides a secure session, but no authentication. This allows any +client to connect, and provides an encrypted session. + +@example +qemu [...OPTIONS...] -vnc :1,tls,x509=/etc/pki/qemu -monitor stdio +@end example + +In the above example @code{/etc/pki/qemu} should contain at least three files, +@code{ca-cert.pem}, @code{server-cert.pem} and @code{server-key.pem}. Unprivileged +users will want to use a private directory, for example @code{$HOME/.pki/qemu}. +NB the @code{server-key.pem} file should be protected with file mode 0600 to +only be readable by the user owning it. + +@node vnc_sec_certificate_verify +@subsection With x509 certificates and client verification + +Certificates can also provide a means to authenticate the client connecting. +The server will request that the client provide a certificate, which it will +then validate against the CA certificate. This is a good choice if deploying +in an environment with a private internal certificate authority. + +@example +qemu [...OPTIONS...] -vnc :1,tls,x509verify=/etc/pki/qemu -monitor stdio +@end example + + +@node vnc_sec_certificate_pw +@subsection With x509 certificates, client verification and passwords + +Finally, the previous method can be combined with VNC password authentication +to provide two layers of authentication for clients. + +@example +qemu [...OPTIONS...] -vnc :1,password,tls,x509verify=/etc/pki/qemu -monitor stdio +(qemu) change vnc password +Password: ******** +(qemu) +@end example + +@node vnc_generate_cert +@subsection Generating certificates for VNC + +The GNU TLS packages provides a command called @code{certtool} which can +be used to generate certificates and keys in PEM format. At a minimum it +is neccessary to setup a certificate authority, and issue certificates to +each server. If using certificates for authentication, then each client +will also need to be issued a certificate. The recommendation is for the +server to keep its certificates in either @code{/etc/pki/qemu} or for +unprivileged users in @code{$HOME/.pki/qemu}. + +@menu +* vnc_generate_ca:: +* vnc_generate_server:: +* vnc_generate_client:: +@end menu +@node vnc_generate_ca +@subsubsection Setup the Certificate Authority + +This step only needs to be performed once per organization / organizational +unit. First the CA needs a private key. This key must be kept VERY secret +and secure. If this key is compromised the entire trust chain of the certificates +issued with it is lost. + +@example +# certtool --generate-privkey > ca-key.pem +@end example + +A CA needs to have a public certificate. For simplicity it can be a self-signed +certificate, or one issue by a commercial certificate issuing authority. To +generate a self-signed certificate requires one core piece of information, the +name of the organization. + +@example +# cat > ca.info < server.info < server-key.pem +# certtool --generate-certificate \ + --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem \ + --load-privkey server server-key.pem \ + --template server.info \ + --outfile server-cert.pem +@end example + +The @code{server-key.pem} and @code{server-cert.pem} files should now be securely copied +to the server for which they were generated. The @code{server-key.pem} is security +sensitive and should be kept protected with file mode 0600 to prevent disclosure. + +@node vnc_generate_client +@subsubsection Issuing client certificates + +If the QEMU VNC server is to use the @code{x509verify} option to validate client +certificates as its authentication mechanism, each client also needs to be issued +a certificate. The client certificate contains enough metadata to uniquely identify +the client, typically organization, state, city, building, etc. On the host holding +the secure CA private key: + +@example +# cat > client.info < client-key.pem +# certtool --generate-certificate \ + --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem \ + --load-privkey client-key.pem \ + --template client.info \ + --outfile client-cert.pem +@end example + +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 gdb_usage @section GDB usage @@ -1513,7 +2003,7 @@ Bartlett): go to the Control Panel => Add/Remove Hardware & Next => Add/Troubleshoot a device => Add a new device & Next => No, select the hardware from a list & Next => NT Apm/Legacy Support & Next => Next (again) a few times. Now the driver is installed and Windows 2000 now -correctly instructs QEMU to shutdown at the appropriate moment. +correctly instructs QEMU to shutdown at the appropriate moment. @subsubsection Share a directory between Unix and Windows @@ -1552,11 +2042,11 @@ differences are mentioned in the following sections. @menu * QEMU PowerPC System emulator:: -* Sparc32 System emulator invocation:: -* Sparc64 System emulator invocation:: -* MIPS System emulator invocation:: -* ARM System emulator invocation:: -* ColdFire System emulator invocation:: +* Sparc32 System emulator:: +* Sparc64 System emulator:: +* MIPS System emulator:: +* ARM System emulator:: +* ColdFire System emulator:: @end menu @node QEMU PowerPC System emulator @@ -1568,13 +2058,13 @@ or PowerMac PowerPC system. QEMU emulates the following PowerMac peripherals: @itemize @minus -@item -UniNorth PCI Bridge +@item +UniNorth PCI Bridge @item PCI VGA compatible card with VESA Bochs Extensions -@item +@item 2 PMAC IDE interfaces with hard disk and CD-ROM support -@item +@item NE2000 PCI adapters @item Non Volatile RAM @@ -1585,15 +2075,15 @@ VIA-CUDA with ADB keyboard and mouse. QEMU emulates the following PREP peripherals: @itemize @minus -@item +@item PCI Bridge @item PCI VGA compatible card with VESA Bochs Extensions -@item +@item 2 IDE interfaces with hard disk and CD-ROM support @item Floppy disk -@item +@item NE2000 network adapters @item Serial port @@ -1612,32 +2102,36 @@ The following options are specific to the PowerPC emulation: @table @option -@item -g WxH[xDEPTH] +@item -g WxH[xDEPTH] Set the initial VGA graphic mode. The default is 800x600x15. @end table -@c man end +@c man end More information is available at @url{http://perso.magic.fr/l_indien/qemu-ppc/}. -@node Sparc32 System emulator invocation -@section Sparc32 System emulator invocation +@node Sparc32 System emulator +@section Sparc32 System emulator -Use the executable @file{qemu-system-sparc} to simulate a SparcStation 5 -(sun4m architecture). The emulation is somewhat complete. +Use the executable @file{qemu-system-sparc} to simulate a SPARCstation +5, SPARCstation 10, SPARCstation 20, SPARCserver 600MP (sun4m +architecture), SPARCstation 2 (sun4c architecture), SPARCserver 1000, +or SPARCcenter 2000 (sun4d architecture). The emulation is somewhat +complete. SMP up to 16 CPUs is supported, but Linux limits the number +of usable CPUs to 4. -QEMU emulates the following sun4m peripherals: +QEMU emulates the following sun4m/sun4d peripherals: @itemize @minus @item -IOMMU +IOMMU or IO-UNITs @item TCX Frame buffer -@item +@item Lance (Am7990) Ethernet @item Non Volatile RAM M48T08 @@ -1647,10 +2141,14 @@ and power/reset logic @item ESP SCSI controller with hard disk and CD-ROM support @item -Floppy drive +Floppy drive (not on SS-600MP) +@item +CS4231 sound device (only on SS-5, not working yet) @end itemize -The number of peripherals is fixed in the architecture. +The number of peripherals is fixed in the architecture. Maximum +memory size depends on the machine type, for SS-5 it is 256MB and for +others 2047MB. Since version 0.8.2, QEMU uses OpenBIOS @url{http://www.openbios.org/}. OpenBIOS is a free (GPL v2) portable @@ -1663,13 +2161,14 @@ Solaris kernels don't work. @c man begin OPTIONS -The following options are specific to the Sparc emulation: +The following options are specific to the Sparc32 emulation: @table @option -@item -g WxH +@item -g WxHx[xDEPTH] -Set the initial TCX graphic mode. The default is 1024x768. +Set the initial TCX graphic mode. The default is 1024x768x8, currently +the only other possible mode is 1024x768x24. @item -prom-env string @@ -1680,12 +2179,16 @@ qemu-system-sparc -prom-env 'auto-boot?=false' \ -prom-env 'boot-device=sd(0,2,0):d' -prom-env 'boot-args=linux single' @end example +@item -M [SS-5|SS-10|SS-20|SS-600MP|SS-2|SS-1000|SS-2000] + +Set the emulated machine type. Default is SS-5. + @end table -@c man end +@c man end -@node Sparc64 System emulator invocation -@section Sparc64 System emulator invocation +@node Sparc64 System emulator +@section Sparc64 System emulator Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine. The emulator is not usable for anything yet. @@ -1694,7 +2197,7 @@ QEMU emulates the following sun4u peripherals: @itemize @minus @item -UltraSparc IIi APB PCI Bridge +UltraSparc IIi APB PCI Bridge @item PCI VGA compatible card with VESA Bochs Extensions @item @@ -1703,26 +2206,103 @@ Non Volatile RAM M48T59 PC-compatible serial ports @end itemize -@node MIPS System emulator invocation -@section MIPS System emulator invocation +@node MIPS System emulator +@section MIPS System emulator -Use the executable @file{qemu-system-mips} to simulate a MIPS machine. -The emulator is able to boot a Linux kernel and to run a Linux Debian -installation from NFS. The following devices are emulated: +Four executables cover simulation of 32 and 64-bit MIPS systems in +both endian options, @file{qemu-system-mips}, @file{qemu-system-mipsel} +@file{qemu-system-mips64} and @file{qemu-system-mips64el}. +Five different machine types are emulated: @itemize @minus -@item -MIPS R4K CPU +@item +A generic ISA PC-like machine "mips" +@item +The MIPS Malta prototype board "malta" +@item +An ACER Pica "pica61". This machine needs the 64-bit emulator. +@item +MIPS emulator pseudo board "mipssim" +@item +A MIPS Magnum R4000 machine "magnum". This machine needs the 64-bit emulator. +@end itemize + +The generic emulation is supported by Debian 'Etch' and is able to +install Debian into a virtual disk image. The following devices are +emulated: + +@itemize @minus +@item +A range of MIPS CPUs, default is the 24Kf @item PC style serial port @item +PC style IDE disk +@item NE2000 network card @end itemize -More information is available in the QEMU mailing-list archive. +The Malta emulation supports the following devices: -@node ARM System emulator invocation -@section ARM System emulator invocation +@itemize @minus +@item +Core board with MIPS 24Kf CPU and Galileo system controller +@item +PIIX4 PCI/USB/SMbus controller +@item +The Multi-I/O chip's serial device +@item +PCnet32 PCI network card +@item +Malta FPGA serial device +@item +Cirrus VGA graphics card +@end itemize + +The ACER Pica emulation supports: + +@itemize @minus +@item +MIPS R4000 CPU +@item +PC-style IRQ and DMA controllers +@item +PC Keyboard +@item +IDE controller +@end itemize + +The mipssim pseudo board emulation provides an environment similiar +to what the proprietary MIPS emulator uses for running Linux. +It supports: + +@itemize @minus +@item +A range of MIPS CPUs, default is the 24Kf +@item +PC style serial port +@item +MIPSnet network emulation +@end itemize + +The MIPS Magnum R4000 emulation supports: + +@itemize @minus +@item +MIPS R4000 CPU +@item +PC-style IRQ controller +@item +PC Keyboard +@item +SCSI controller +@item +G364 framebuffer +@end itemize + + +@node ARM System emulator +@section ARM System emulator Use the executable @file{qemu-system-arm} to simulate a ARM machine. The ARM Integrator/CP board is emulated with the following @@ -1730,10 +2310,10 @@ devices: @itemize @minus @item -ARM926E, ARM1026E or ARM946E CPU +ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU @item Two PL011 UARTs -@item +@item SMC 91c111 Ethernet adapter @item PL110 LCD controller @@ -1747,12 +2327,12 @@ The ARM Versatile baseboard is emulated with the following devices: @itemize @minus @item -ARM926E CPU +ARM926E, ARM1136 or Cortex-A8 CPU @item PL190 Vectored Interrupt Controller @item Four PL011 UARTs -@item +@item SMC 91c111 Ethernet adapter @item PL110 LCD controller @@ -1776,12 +2356,12 @@ The ARM RealView Emulation baseboard is emulated with the following devices: @itemize @minus @item -ARM926E CPU +ARM926E, ARM1136, ARM11MPCORE(x4) or Cortex-A8 CPU @item ARM AMBA Generic/Distributed Interrupt Controller @item Four PL011 UARTs -@item +@item SMC 91c111 Ethernet adapter @item PL110 LCD controller @@ -1827,25 +2407,88 @@ Three on-chip UARTs WM8750 audio CODEC on I@math{^2}C and I@math{^2}S busses @end itemize +The Palm Tungsten|E PDA (codename "Cheetah") emulation includes the +following elements: + +@itemize @minus +@item +Texas Instruments OMAP310 System-on-chip (ARM 925T core) +@item +ROM and RAM memories (ROM firmware image can be loaded with -option-rom) +@item +On-chip LCD controller +@item +On-chip Real Time Clock +@item +TI TSC2102i touchscreen controller / analog-digital converter / Audio +CODEC, connected through MicroWire and I@math{^2}S busses +@item +GPIO-connected matrix keypad +@item +Secure Digital card connected to OMAP MMC/SD host +@item +Three on-chip UARTs +@end itemize + +The Luminary Micro Stellaris LM3S811EVB emulation includes the following +devices: + +@itemize @minus +@item +Cortex-M3 CPU core. +@item +64k Flash and 8k SRAM. +@item +Timers, UARTs, ADC and I@math{^2}C interface. +@item +OSRAM Pictiva 96x16 OLED with SSD0303 controller on I@math{^2}C bus. +@end itemize + +The Luminary Micro Stellaris LM3S6965EVB emulation includes the following +devices: + +@itemize @minus +@item +Cortex-M3 CPU core. +@item +256k Flash and 64k SRAM. +@item +Timers, UARTs, ADC, I@math{^2}C and SSI interfaces. +@item +OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via SSI. +@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. -@node ColdFire System emulator invocation -@section ColdFire System emulator invocation +@node ColdFire System emulator +@section ColdFire System emulator Use the executable @file{qemu-system-m68k} to simulate a ColdFire machine. The emulator is able to boot a uClinux kernel. -The following devices are emulated: + +The M5208EVB emulation includes the following devices: @itemize @minus -@item +@item +MCF5208 ColdFire V2 Microprocessor (ISA A+ with EMAC). +@item +Three Two on-chip UARTs. +@item +Fast Ethernet Controller (FEC) +@end itemize + +The AN5206 emulation includes the following devices: + +@itemize @minus +@item MCF5206 ColdFire V2 Microprocessor. @item Two on-chip UARTs. @end itemize -@node QEMU User space emulator -@chapter QEMU User space emulator +@node QEMU User space emulator +@chapter QEMU User space emulator @menu * Supported Operating Systems :: @@ -1879,14 +2522,14 @@ Mac OS X/Darwin (referred as qemu-darwin-user) @subsection Quick Start In order to launch a Linux process, QEMU needs the process executable -itself and all the target (x86) dynamic libraries used by it. +itself and all the target (x86) dynamic libraries used by it. @itemize @item On x86, you can just try to launch any process by using the native libraries: -@example +@example qemu-i386 -L / /bin/ls @end example @@ -1896,7 +2539,7 @@ qemu-i386 -L / /bin/ls @item Since QEMU is also a linux process, you can launch qemu with qemu (NOTE: you can only do that if you compiled QEMU from the sources): -@example +@example qemu-i386 -L / qemu-i386 -L / /bin/ls @end example @@ -1905,7 +2548,7 @@ qemu-i386 -L / qemu-i386 -L / /bin/ls @code{LD_LIBRARY_PATH} is not set: @example -unset LD_LIBRARY_PATH +unset LD_LIBRARY_PATH @end example Then you can launch the precompiled @file{ls} x86 executable: @@ -1940,7 +2583,7 @@ qemu-i386 /usr/local/qemu-i386/bin/ls-i386 @end example @item Download the binary x86 Wine install -(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). +(@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). @item Configure Wine on your account. Look at the provided script @file{/usr/local/qemu-i386/@/bin/wine-conf.sh}. Your previous @@ -1965,7 +2608,7 @@ usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] @table @option @item -h Print the help -@item -L path +@item -L path Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) @item -s size Set the x86 stack size in bytes (default=524288) @@ -1980,6 +2623,18 @@ Activate log (logfile=/tmp/qemu.log) Act as if the host page size was 'pagesize' bytes @end table +Environment variables: + +@table @env +@item QEMU_STRACE +Print system calls and arguments similar to the 'strace' program +(NOTE: the actual 'strace' program will not work because the user +space emulator hasn't implemented ptrace). At the moment this is +incomplete. All system calls that don't have a specific argument +format are printed with information for six arguments. Many +flag-style arguments don't have decoders and will show up as numbers. +@end table + @node Other binaries @subsection Other binaries @@ -1993,6 +2648,12 @@ coldfire uClinux bFLT format binaries. The binary format is detected automatically. +@command{qemu-sparc32plus} can execute Sparc32 and SPARC32PLUS binaries +(Sparc64 CPU, 32 bit ABI). + +@command{qemu-sparc64} can execute some Sparc64 (Sparc64 CPU, 64 bit ABI) and +SPARC32PLUS binaries (Sparc64 CPU, 32 bit ABI). + @node Mac OS X/Darwin User space emulator @section Mac OS X/Darwin User space emulator @@ -2031,20 +2692,20 @@ CD or compile them by hand. @item On x86, you can just try to launch any process by using the native libraries: -@example +@example qemu-i386 /bin/ls @end example or to run the ppc version of the executable: -@example +@example qemu-ppc /bin/ls @end example @item On ppc, you'll have to tell qemu where your x86 libraries (and dynamic linker) are installed: -@example +@example qemu-i386 -L /opt/x86_root/ /bin/ls @end example @@ -2063,7 +2724,7 @@ usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] @table @option @item -h Print the help -@item -L path +@item -L path Set the library root path (default=/) @item -s size Set the stack size in bytes (default=524288) @@ -2130,7 +2791,7 @@ these older versions so that usually you don't have to do anything. @url{http://www.mingw.org/}. You can find detailed installation instructions in the download section and the FAQ. -@item Download +@item Download the MinGW development library of SDL 1.2.x (@file{SDL-devel-1.2.x-@/mingw32.tar.gz}) from @url{http://www.libsdl.org}. Unpack it in a temporary place, and @@ -2139,14 +2800,14 @@ directory. Edit the @file{sdl-config} script so that it gives the correct SDL directory when invoked. @item Extract the current version of QEMU. - + @item Start the MSYS shell (file @file{msys.bat}). -@item Change to the QEMU directory. Launch @file{./configure} and +@item Change to the QEMU directory. Launch @file{./configure} and @file{make}. If you have problems using SDL, verify that @file{sdl-config} can be launched from the MSYS command line. -@item You can install QEMU in @file{Program Files/Qemu} by typing +@item You can install QEMU in @file{Program Files/Qemu} by typing @file{make install}. Don't forget to copy @file{SDL.dll} in @file{Program Files/Qemu}. @@ -2160,13 +2821,13 @@ correct SDL directory when invoked. Install the MinGW cross compilation tools available at @url{http://www.mingw.org/}. -@item +@item Install the Win32 version of SDL (@url{http://www.libsdl.org}) by unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment variable so that @file{i386-mingw32msvc-sdl-config} can be launched by the QEMU configuration script. -@item +@item Configure QEMU for Windows cross compilation: @example ./configure --enable-mingw32 @@ -2175,9 +2836,9 @@ If necessary, you can change the cross-prefix according to the prefix chosen for the MinGW tools with --cross-prefix. You can also use --prefix to set the Win32 install path. -@item You can install QEMU in the installation directory by typing +@item You can install QEMU in the installation directory by typing @file{make install}. Don't forget to copy @file{SDL.dll} in the -installation directory. +installation directory. @end itemize