git.maemo.org Git - qemu/blob - qemu/qemu-doc.html

   1 <HTML>
   2 <HEAD>
   3 <!-- Created by texi2html 1.56k from qemu-doc.texi on 19 December 2005 -->
   4
   5 <TITLE>QEMU CPU Emulator User Documentation</TITLE>
   6 </HEAD>
   7 <BODY>
   8 <H1>QEMU CPU Emulator User Documentation</H1>
   9 <P>
  10 <P><HR><P>
  11 <H1>Table of Contents</H1>
  12 <UL>
  13 <LI><A NAME="TOC1" HREF="qemu-doc.html#SEC1">1. Introduction</A>
  14 <UL>
  15 <LI><A NAME="TOC2" HREF="qemu-doc.html#SEC2">1.1 Features</A>
  16 </UL>
  17 <LI><A NAME="TOC3" HREF="qemu-doc.html#SEC3">2. Installation</A>
  18 <UL>
  19 <LI><A NAME="TOC4" HREF="qemu-doc.html#SEC4">2.1 Linux</A>
  20 <LI><A NAME="TOC5" HREF="qemu-doc.html#SEC5">2.2 Windows</A>
  21 <LI><A NAME="TOC6" HREF="qemu-doc.html#SEC6">2.3 Mac OS X</A>
  22 </UL>
  23 <LI><A NAME="TOC7" HREF="qemu-doc.html#SEC7">3. QEMU PC System emulator</A>
  24 <UL>
  25 <LI><A NAME="TOC8" HREF="qemu-doc.html#SEC8">3.1 Introduction</A>
  26 <LI><A NAME="TOC9" HREF="qemu-doc.html#SEC9">3.2 Quick Start</A>
  27 <LI><A NAME="TOC10" HREF="qemu-doc.html#SEC10">3.3 Invocation</A>
  28 <LI><A NAME="TOC11" HREF="qemu-doc.html#SEC11">3.4 Keys</A>
  29 <LI><A NAME="TOC12" HREF="qemu-doc.html#SEC12">3.5 QEMU Monitor</A>
  30 <UL>
  31 <LI><A NAME="TOC13" HREF="qemu-doc.html#SEC13">3.5.1 Commands</A>
  32 <LI><A NAME="TOC14" HREF="qemu-doc.html#SEC14">3.5.2 Integer expressions</A>
  33 </UL>
  34 <LI><A NAME="TOC15" HREF="qemu-doc.html#SEC15">3.6 Disk Images</A>
  35 <UL>
  36 <LI><A NAME="TOC16" HREF="qemu-doc.html#SEC16">3.6.1 Quick start for disk image creation</A>
  37 <LI><A NAME="TOC17" HREF="qemu-doc.html#SEC17">3.6.2 Snapshot mode</A>
  38 <LI><A NAME="TOC18" HREF="qemu-doc.html#SEC18">3.6.3 <CODE>qemu-img</CODE> Invocation</A>
  39 <LI><A NAME="TOC19" HREF="qemu-doc.html#SEC19">3.6.4 Virtual FAT disk images</A>
  40 </UL>
  41 <LI><A NAME="TOC20" HREF="qemu-doc.html#SEC20">3.7 Network emulation</A>
  42 <UL>
  43 <LI><A NAME="TOC21" HREF="qemu-doc.html#SEC21">3.7.1 VLANs</A>
  44 <LI><A NAME="TOC22" HREF="qemu-doc.html#SEC22">3.7.2 Using TAP network interfaces</A>
  45 <LI><A NAME="TOC23" HREF="qemu-doc.html#SEC23">3.7.3 Using the user mode network stack</A>
  46 <LI><A NAME="TOC24" HREF="qemu-doc.html#SEC24">3.7.4 Connecting VLANs between QEMU instances</A>
  47 </UL>
  48 <LI><A NAME="TOC25" HREF="qemu-doc.html#SEC25">3.8 Direct Linux Boot</A>
  49 <LI><A NAME="TOC26" HREF="qemu-doc.html#SEC26">3.9 USB emulation</A>
  50 <UL>
  51 <LI><A NAME="TOC27" HREF="qemu-doc.html#SEC27">3.9.1 Using virtual USB devices</A>
  52 <LI><A NAME="TOC28" HREF="qemu-doc.html#SEC28">3.9.2 Using host USB devices on a Linux host</A>
  53 </UL>
  54 <LI><A NAME="TOC29" HREF="qemu-doc.html#SEC29">3.10 GDB usage</A>
  55 <LI><A NAME="TOC30" HREF="qemu-doc.html#SEC30">3.11 Target OS specific information</A>
  56 <UL>
  57 <LI><A NAME="TOC31" HREF="qemu-doc.html#SEC31">3.11.1 Linux</A>
  58 <LI><A NAME="TOC32" HREF="qemu-doc.html#SEC32">3.11.2 Windows</A>
  59 <UL>
  60 <LI><A NAME="TOC33" HREF="qemu-doc.html#SEC33">3.11.2.1 SVGA graphic modes support</A>
  61 <LI><A NAME="TOC34" HREF="qemu-doc.html#SEC34">3.11.2.2 CPU usage reduction</A>
  62 <LI><A NAME="TOC35" HREF="qemu-doc.html#SEC35">3.11.2.3 Windows 2000 disk full problem</A>
  63 <LI><A NAME="TOC36" HREF="qemu-doc.html#SEC36">3.11.2.4 Windows 2000 shutdown</A>
  64 <LI><A NAME="TOC37" HREF="qemu-doc.html#SEC37">3.11.2.5 Share a directory between Unix and Windows</A>
  65 <LI><A NAME="TOC38" HREF="qemu-doc.html#SEC38">3.11.2.6 Windows XP security problems</A>
  66 </UL>
  67 <LI><A NAME="TOC39" HREF="qemu-doc.html#SEC39">3.11.3 MS-DOS and FreeDOS</A>
  68 <UL>
  69 <LI><A NAME="TOC40" HREF="qemu-doc.html#SEC40">3.11.3.1 CPU usage reduction</A>
  70 </UL>
  71 </UL>
  72 </UL>
  73 <LI><A NAME="TOC41" HREF="qemu-doc.html#SEC41">4. QEMU System emulator for non PC targets</A>
  74 <UL>
  75 <LI><A NAME="TOC42" HREF="qemu-doc.html#SEC42">4.1 QEMU PowerPC System emulator</A>
  76 <LI><A NAME="TOC43" HREF="qemu-doc.html#SEC43">4.2 Sparc32 System emulator invocation</A>
  77 <LI><A NAME="TOC44" HREF="qemu-doc.html#SEC44">4.3 Sparc64 System emulator invocation</A>
  78 <LI><A NAME="TOC45" HREF="qemu-doc.html#SEC45">4.4 MIPS System emulator invocation</A>
  79 <LI><A NAME="TOC46" HREF="qemu-doc.html#SEC46">4.5 ARM System emulator invocation</A>
  80 </UL>
  81 <LI><A NAME="TOC47" HREF="qemu-doc.html#SEC47">5. QEMU Linux User space emulator</A>
  82 <UL>
  83 <LI><A NAME="TOC48" HREF="qemu-doc.html#SEC48">5.1 Quick Start</A>
  84 <LI><A NAME="TOC49" HREF="qemu-doc.html#SEC49">5.2 Wine launch</A>
  85 <LI><A NAME="TOC50" HREF="qemu-doc.html#SEC50">5.3 Command line options</A>
  86 </UL>
  87 <LI><A NAME="TOC51" HREF="qemu-doc.html#SEC51">6. Compilation from the sources</A>
  88 <UL>
  89 <LI><A NAME="TOC52" HREF="qemu-doc.html#SEC52">6.1 Linux/Unix</A>
  90 <UL>
  91 <LI><A NAME="TOC53" HREF="qemu-doc.html#SEC53">6.1.1 Compilation</A>
  92 <LI><A NAME="TOC54" HREF="qemu-doc.html#SEC54">6.1.2 Tested tool versions</A>
  93 </UL>
  94 <LI><A NAME="TOC55" HREF="qemu-doc.html#SEC55">6.2 Windows</A>
  95 <LI><A NAME="TOC56" HREF="qemu-doc.html#SEC56">6.3 Cross compilation for Windows with Linux</A>
  96 <LI><A NAME="TOC57" HREF="qemu-doc.html#SEC57">6.4 Mac OS X</A>
  97 </UL>
  98 </UL>
  99 <P><HR><P>
 100
 101 <P>
 102 QEMU CPU Emulator User Documentation
 103
 104
 105
 106
 107 <H1><A NAME="SEC1" HREF="qemu-doc.html#TOC1">1. Introduction</A></H1>
 108
 109
 110
 111 <H2><A NAME="SEC2" HREF="qemu-doc.html#TOC2">1.1 Features</A></H2>
 112
 113 <P>
 114 QEMU is a FAST! processor emulator using dynamic translation to
 115 achieve good emulation speed.
 116
 117
 118 <P>
 119 QEMU has two operating modes:
 120
 121
 122
 123 <UL>
 124
 125 <LI>
 126
 127 Full system emulation. In this mode, QEMU emulates a full system (for
 128 example a PC), including one or several processors and various
 129 peripherals. It can be used to launch different Operating Systems
 130 without rebooting the PC or to debug system code.
 131
 132 <LI>
 133
 134 User mode emulation (Linux host only). In this mode, QEMU can launch
 135 Linux processes compiled for one CPU on another CPU. It can be used to
 136 launch the Wine Windows API emulator (<A HREF="http://www.winehq.org">http://www.winehq.org</A>) or
 137 to ease cross-compilation and cross-debugging.
 138
 139 </UL>
 140
 141 <P>
 142 QEMU can run without an host kernel driver and yet gives acceptable
 143 performance.
 144
 145
 146 <P>
 147 For system emulation, the following hardware targets are supported:
 148
 149 <UL>
 150 <LI>PC (x86 or x86_64 processor)
 151
 152 <LI>ISA PC (old style PC without PCI bus)
 153
 154 <LI>PREP (PowerPC processor)
 155
 156 <LI>G3 BW PowerMac (PowerPC processor)
 157
 158 <LI>Mac99 PowerMac (PowerPC processor, in progress)
 159
 160 <LI>Sun4m (32-bit Sparc processor)
 161
 162 <LI>Sun4u (64-bit Sparc processor, in progress)
 163
 164 <LI>Malta board (32-bit MIPS processor)
 165
 166 <LI>ARM Integrator/CP (ARM1026E processor)
 167
 168 </UL>
 169
 170 <P>
 171 For user emulation, x86, PowerPC, ARM, MIPS, and Sparc32/64 CPUs are supported.
 172
 173
 174
 175
 176 <H1><A NAME="SEC3" HREF="qemu-doc.html#TOC3">2. Installation</A></H1>
 177
 178 <P>
 179 If you want to compile QEMU yourself, see section <A HREF="qemu-doc.html#SEC51">6. Compilation from the sources</A>.
 180
 181
 182
 183
 184 <H2><A NAME="SEC4" HREF="qemu-doc.html#TOC4">2.1 Linux</A></H2>
 185
 186 <P>
 187 If a precompiled package is available for your distribution - you just
 188 have to install it. Otherwise, see section <A HREF="qemu-doc.html#SEC51">6. Compilation from the sources</A>.
 189
 190
 191
 192
 193 <H2><A NAME="SEC5" HREF="qemu-doc.html#TOC5">2.2 Windows</A></H2>
 194
 195 <P>
 196 Download the experimental binary installer at
 197 <A HREF="http://www.freeoszoo.org/download.php">http://www.freeoszoo.org/download.php</A>.
 198
 199
 200
 201
 202 <H2><A NAME="SEC6" HREF="qemu-doc.html#TOC6">2.3 Mac OS X</A></H2>
 203
 204 <P>
 205 Download the experimental binary installer at
 206 <A HREF="http://www.freeoszoo.org/download.php">http://www.freeoszoo.org/download.php</A>.
 207
 208
 209
 210
 211 <H1><A NAME="SEC7" HREF="qemu-doc.html#TOC7">3. QEMU PC System emulator</A></H1>
 212
 213
 214
 215 <H2><A NAME="SEC8" HREF="qemu-doc.html#TOC8">3.1 Introduction</A></H2>
 216
 217 <P>
 218 The QEMU PC System emulator simulates the
 219 following peripherals:
 220
 221
 222
 223 <UL>
 224 <LI>
 225
 226 i440FX host PCI bridge and PIIX3 PCI to ISA bridge
 227 <LI>
 228
 229 Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA
 230 extensions (hardware level, including all non standard modes).
 231 <LI>
 232
 233 PS/2 mouse and keyboard
 234 <LI>
 235
 236 2 PCI IDE interfaces with hard disk and CD-ROM support
 237 <LI>
 238
 239 Floppy disk
 240 <LI>
 241
 242 NE2000 PCI network adapters
 243 <LI>
 244
 245 Serial ports
 246 <LI>
 247
 248 Creative SoundBlaster 16 sound card
 249 <LI>
 250
 251 ENSONIQ AudioPCI ES1370 sound card
 252 <LI>
 253
 254 Adlib(OPL2) - Yamaha YM3812 compatible chip
 255 <LI>
 256
 257 PCI UHCI USB controller and a virtual USB hub.
 258 </UL>
 259
 260 <P>
 261 SMP is supported with up to 255 CPUs.
 262
 263
 264 <P>
 265 Note that adlib is only available when QEMU was configured with
 266 -enable-adlib
 267
 268
 269 <P>
 270 QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL
 271 VGA BIOS.
 272
 273
 274 <P>
 275 QEMU uses YM3812 emulation by Tatsuyuki Satoh.
 276
 277
 278
 279
 280 <H2><A NAME="SEC9" HREF="qemu-doc.html#TOC9">3.2 Quick Start</A></H2>
 281
 282 <P>
 283 Download and uncompress the linux image (<TT>`linux.img'</TT>) and type:
 284
 285
 286
 287 <PRE>
 288 qemu linux.img
 289 </PRE>
 290
 291 <P>
 292 Linux should boot and give you a prompt.
 293
 294
 295
 296
 297 <H2><A NAME="SEC10" HREF="qemu-doc.html#TOC10">3.3 Invocation</A></H2>
 298
 299
 300 <PRE>
 301 usage: qemu [options] [disk_image]
 302 </PRE>
 303
 304 <P>
 305 <VAR>disk_image</VAR> is a raw hard disk image for IDE hard disk 0.
 306
 307
 308 <P>
 309 General options:
 310 <DL COMPACT>
 311
 312 <DT><SAMP>`-M machine'</SAMP>
 313 <DD>
 314 Select the emulated machine (<CODE>-M ?</CODE> for list)
 315
 316 <DT><SAMP>`-fda file'</SAMP>
 317 <DD>
 318 <DT><SAMP>`-fdb file'</SAMP>
 319 <DD>
 320 Use <VAR>file</VAR> as floppy disk 0/1 image (See section <A HREF="qemu-doc.html#SEC15">3.6 Disk Images</A>). You can
 321 use the host floppy by using <TT>`/dev/fd0'</TT> as filename.
 322
 323 <DT><SAMP>`-hda file'</SAMP>
 324 <DD>
 325 <DT><SAMP>`-hdb file'</SAMP>
 326 <DD>
 327 <DT><SAMP>`-hdc file'</SAMP>
 328 <DD>
 329 <DT><SAMP>`-hdd file'</SAMP>
 330 <DD>
 331 Use <VAR>file</VAR> as hard disk 0, 1, 2 or 3 image (See section <A HREF="qemu-doc.html#SEC15">3.6 Disk Images</A>).
 332
 333 <DT><SAMP>`-cdrom file'</SAMP>
 334 <DD>
 335 Use <VAR>file</VAR> as CD-ROM image (you cannot use <SAMP>`-hdc'</SAMP> and and
 336 <SAMP>`-cdrom'</SAMP> at the same time). You can use the host CD-ROM by
 337 using <TT>`/dev/cdrom'</TT> as filename.
 338
 339 <DT><SAMP>`-boot [a|c|d]'</SAMP>
 340 <DD>
 341 Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is
 342 the default.
 343
 344 <DT><SAMP>`-snapshot'</SAMP>
 345 <DD>
 346 Write to temporary files instead of disk image files. In this case,
 347 the raw disk image you use is not written back. You can however force
 348 the write back by pressing <KBD>C-a s</KBD> (See section <A HREF="qemu-doc.html#SEC15">3.6 Disk Images</A>).
 349
 350 <DT><SAMP>`-m megs'</SAMP>
 351 <DD>
 352 Set virtual RAM size to <VAR>megs</VAR> megabytes. Default is 128 MB.
 353
 354 <DT><SAMP>`-smp n'</SAMP>
 355 <DD>
 356 Simulate an SMP system with <VAR>n</VAR> CPUs. On the PC target, up to 255
 357 CPUs are supported.
 358
 359 <DT><SAMP>`-nographic'</SAMP>
 360 <DD>
 361 Normally, QEMU uses SDL to display the VGA output. With this option,
 362 you can totally disable graphical output so that QEMU is a simple
 363 command line application. The emulated serial port is redirected on
 364 the console. Therefore, you can still use QEMU to debug a Linux kernel
 365 with a serial console.
 366
 367 <DT><SAMP>`-k language'</SAMP>
 368 <DD>
 369 Use keyboard layout <VAR>language</VAR> (for example <CODE>fr</CODE> for
 370 French). This option is only needed where it is not easy to get raw PC
 371 keycodes (e.g. on Macs or with some X11 servers). You don't need to
 372 use it on PC/Linux or PC/Windows hosts.
 373
 374 The available layouts are:
 375
 376 <PRE>
 377 ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
 378 da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
 379 de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
 380 </PRE>
 381
 382 The default is <CODE>en-us</CODE>.
 383
 384 <DT><SAMP>`-audio-help'</SAMP>
 385 <DD>
 386 Will show the audio subsystem help: list of drivers, tunable
 387 parameters.
 388
 389 <DT><SAMP>`-soundhw card1,card2,... or -soundhw all'</SAMP>
 390 <DD>
 391 Enable audio and selected sound hardware. Use ? to print all
 392 available sound hardware.
 393
 394
 395 <PRE>
 396 qemu -soundhw sb16,adlib hda
 397 qemu -soundhw es1370 hda
 398 qemu -soundhw all hda
 399 qemu -soundhw ?
 400 </PRE>
 401
 402 <DT><SAMP>`-localtime'</SAMP>
 403 <DD>
 404 Set the real time clock to local time (the default is to UTC
 405 time). This option is needed to have correct date in MS-DOS or
 406 Windows.
 407
 408 <DT><SAMP>`-full-screen'</SAMP>
 409 <DD>
 410 Start in full screen.
 411
 412 <DT><SAMP>`-pidfile file'</SAMP>
 413 <DD>
 414 Store the QEMU process PID in <VAR>file</VAR>. It is useful if you launch QEMU
 415 from a script.
 416
 417 <DT><SAMP>`-win2k-hack'</SAMP>
 418 <DD>
 419 Use it when installing Windows 2000 to avoid a disk full bug. After
 420 Windows 2000 is installed, you no longer need this option (this option
 421 slows down the IDE transfers).
 422
 423 </DL>
 424
 425 <P>
 426 USB options:
 427 <DL COMPACT>
 428
 429 <DT><SAMP>`-usb'</SAMP>
 430 <DD>
 431 Enable the USB driver (will be the default soon)
 432
 433 <DT><SAMP>`-usbdevice devname'</SAMP>
 434 <DD>
 435 Add the USB device <VAR>devname</VAR>. See the monitor command
 436 <CODE>usb_add</CODE> to have more information.
 437 </DL>
 438
 439 <P>
 440 Network options:
 441
 442
 443 <DL COMPACT>
 444
 445 <DT><SAMP>`-net nic[,vlan=n][,macaddr=addr]'</SAMP>
 446 <DD>
 447 Create a new Network Interface Card and connect it to VLAN <VAR>n</VAR> (<VAR>n</VAR>
 448 = 0 is the default). The NIC is currently an NE2000 on the PC
 449 target. Optionally, the MAC address can be changed. If no
 450 <SAMP>`-net'</SAMP> option is specified, a single NIC is created.
 451
 452 <DT><SAMP>`-net user[,vlan=n]'</SAMP>
 453 <DD>
 454 Use the user mode network stack which requires no administrator
 455 priviledge to run. This is the default if no <SAMP>`-net'</SAMP> option is
 456 specified.
 457
 458 <DT><SAMP>`-net tap[,vlan=n][,fd=h][,ifname=name][,script=file]'</SAMP>
 459 <DD>
 460 Connect the host TAP network interface <VAR>name</VAR> to VLAN <VAR>n</VAR> and
 461 use the network script <VAR>file</VAR> to configure it. The default
 462 network script is <TT>`/etc/qemu-ifup'</TT>. If <VAR>name</VAR> is not
 463 provided, the OS automatically provides one.  <SAMP>`fd=h'</SAMP> can be
 464 used to specify the handle of an already opened host TAP interface. Example:
 465
 466
 467 <PRE>
 468 qemu linux.img -net nic -net tap
 469 </PRE>
 470
 471 More complicated example (two NICs, each one connected to a TAP device)
 472
 473 <PRE>
 474 qemu linux.img -net nic,vlan=0 -net tap,vlan=0,ifname=tap0 \
 475                -net nic,vlan=1 -net tap,vlan=1,ifname=tap1
 476 </PRE>
 477
 478 <DT><SAMP>`-net socket[,vlan=n][,fd=h][,listen=[host]:port][,connect=host:port]'</SAMP>
 479 <DD>
 480 Connect the VLAN <VAR>n</VAR> to a remote VLAN in another QEMU virtual
 481 machine using a TCP socket connection. If <SAMP>`listen'</SAMP> is
 482 specified, QEMU waits for incoming connections on <VAR>port</VAR>
 483 (<VAR>host</VAR> is optional). <SAMP>`connect'</SAMP> is used to connect to
 484 another QEMU instance using the <SAMP>`listen'</SAMP> option. <SAMP>`fd=h'</SAMP>
 485 specifies an already opened TCP socket.
 486
 487 Example:
 488
 489 <PRE>
 490 # launch a first QEMU instance
 491 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,listen=:1234
 492 # connect the VLAN 0 of this instance to the VLAN 0 of the first instance
 493 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,connect=127.0.0.1:1234
 494 </PRE>
 495
 496 <DT><SAMP>`-net socket[,vlan=n][,fd=h][,mcast=maddr:port]'</SAMP>
 497 <DD>
 498 Create a VLAN <VAR>n</VAR> shared with another QEMU virtual
 499 machines using a UDP multicast socket, effectively making a bus for
 500 every QEMU with same multicast address <VAR>maddr</VAR> and <VAR>port</VAR>.
 501 NOTES:
 502
 503 <OL>
 504 <LI>
 505
 506 Several QEMU can be running on different hosts and share same bus (assuming
 507 correct multicast setup for these hosts).
 508 <LI>
 509
 510 mcast support is compatible with User Mode Linux (argument <SAMP>`eth<VAR>N</VAR>=mcast'</SAMP>), see
 511 <A HREF="http://user-mode-linux.sf.net">http://user-mode-linux.sf.net</A>.
 512 <LI>Use <SAMP>`fd=h'</SAMP> to specify an already opened UDP multicast socket.
 513
 514 </OL>
 515
 516 Example:
 517
 518 <PRE>
 519 # launch one QEMU instance
 520 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=230.0.0.1:1234
 521 # launch another QEMU instance on same "bus"
 522 qemu linux.img -net nic,macaddr=52:54:00:12:34:57 -net socket,mcast=230.0.0.1:1234
 523 # launch yet another QEMU instance on same "bus"
 524 qemu linux.img -net nic,macaddr=52:54:00:12:34:58 -net socket,mcast=230.0.0.1:1234
 525 </PRE>
 526
 527 Example (User Mode Linux compat.):
 528
 529 <PRE>
 530 # launch QEMU instance (note mcast address selected is UML's default)
 531 qemu linux.img -net nic,macaddr=52:54:00:12:34:56 -net socket,mcast=239.192.168.1:1102
 532 # launch UML
 533 /path/to/linux ubd0=/path/to/root_fs eth0=mcast
 534 </PRE>
 535
 536 <DT><SAMP>`-net none'</SAMP>
 537 <DD>
 538 Indicate that no network devices should be configured. It is used to
 539 override the default configuration which is activated if no
 540 <SAMP>`-net'</SAMP> options are provided.
 541
 542 <DT><SAMP>`-tftp prefix'</SAMP>
 543 <DD>
 544 When using the user mode network stack, activate a built-in TFTP
 545 server. All filenames beginning with <VAR>prefix</VAR> can be downloaded
 546 from the host to the guest using a TFTP client. The TFTP client on the
 547 guest must be configured in binary mode (use the command <CODE>bin</CODE> of
 548 the Unix TFTP client). The host IP address on the guest is as usual
 549 10.0.2.2.
 550
 551 <DT><SAMP>`-smb dir'</SAMP>
 552 <DD>
 553 When using the user mode network stack, activate a built-in SMB
 554 server so that Windows OSes can access to the host files in <TT>`dir'</TT>
 555 transparently.
 556
 557 In the guest Windows OS, the line:
 558
 559 <PRE>
 560 10.0.2.4 smbserver
 561 </PRE>
 562
 563 must be added in the file <TT>`C:\WINDOWS\LMHOSTS'</TT> (for windows 9x/Me)
 564 or <TT>`C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS'</TT> (Windows NT/2000).
 565
 566 Then <TT>`dir'</TT> can be accessed in <TT>`\\smbserver\qemu'</TT>.
 567
 568 Note that a SAMBA server must be installed on the host OS in
 569 <TT>`/usr/sbin/smbd'</TT>. QEMU was tested succesfully with smbd version
 570 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3.
 571
 572 <DT><SAMP>`-redir [tcp|udp]:host-port:[guest-host]:guest-port'</SAMP>
 573 <DD>
 574 When using the user mode network stack, redirect incoming TCP or UDP
 575 connections to the host port <VAR>host-port</VAR> to the guest
 576 <VAR>guest-host</VAR> on guest port <VAR>guest-port</VAR>. If <VAR>guest-host</VAR>
 577 is not specified, its value is 10.0.2.15 (default address given by the
 578 built-in DHCP server).
 579
 580 For example, to redirect host X11 connection from screen 1 to guest
 581 screen 0, use the following:
 582
 583
 584 <PRE>
 585 # on the host
 586 qemu -redir tcp:6001::6000 [...]
 587 # this host xterm should open in the guest X11 server
 588 xterm -display :1
 589 </PRE>
 590
 591 To redirect telnet connections from host port 5555 to telnet port on
 592 the guest, use the following:
 593
 594
 595 <PRE>
 596 # on the host
 597 qemu -redir tcp:5555::23 [...]
 598 telnet localhost 5555
 599 </PRE>
 600
 601 Then when you use on the host <CODE>telnet localhost 5555</CODE>, you
 602 connect to the guest telnet server.
 603
 604 </DL>
 605
 606 <P>
 607 Linux boot specific: When using these options, you can use a given
 608 Linux kernel without installing it in the disk image. It can be useful
 609 for easier testing of various kernels.
 610
 611
 612 <DL COMPACT>
 613
 614 <DT><SAMP>`-kernel bzImage'</SAMP>
 615 <DD>
 616 Use <VAR>bzImage</VAR> as kernel image.
 617
 618 <DT><SAMP>`-append cmdline'</SAMP>
 619 <DD>
 620 Use <VAR>cmdline</VAR> as kernel command line
 621
 622 <DT><SAMP>`-initrd file'</SAMP>
 623 <DD>
 624 Use <VAR>file</VAR> as initial ram disk.
 625
 626 </DL>
 627
 628 <P>
 629 Debug/Expert options:
 630 <DL COMPACT>
 631
 632 <DT><SAMP>`-serial dev'</SAMP>
 633 <DD>
 634 Redirect the virtual serial port to host device <VAR>dev</VAR>. Available
 635 devices are:
 636 <DL COMPACT>
 637
 638 <DT><CODE>vc</CODE>
 639 <DD>
 640 Virtual console
 641 <DT><CODE>pty</CODE>
 642 <DD>
 643 [Linux only] Pseudo TTY (a new PTY is automatically allocated)
 644 <DT><CODE>null</CODE>
 645 <DD>
 646 void device
 647 <DT><CODE>/dev/XXX</CODE>
 648 <DD>
 649 [Linux only] Use host tty, e.g. <TT>`/dev/ttyS0'</TT>. The host serial port
 650 parameters are set according to the emulated ones.
 651 <DT><CODE>/dev/parportN</CODE>
 652 <DD>
 653 [Linux only, parallel port only] Use host parallel port
 654 <VAR>N</VAR>. Currently only SPP parallel port features can be used.
 655 <DT><CODE>file:filename</CODE>
 656 <DD>
 657 Write output to filename. No character can be read.
 658 <DT><CODE>stdio</CODE>
 659 <DD>
 660 [Unix only] standard input/output
 661 <DT><CODE>pipe:filename</CODE>
 662 <DD>
 663 [Unix only] name pipe <VAR>filename</VAR>
 664 </DL>
 665 The default device is <CODE>vc</CODE> in graphical mode and <CODE>stdio</CODE> in
 666 non graphical mode.
 667
 668 This option can be used several times to simulate up to 4 serials
 669 ports.
 670
 671 <DT><SAMP>`-parallel dev'</SAMP>
 672 <DD>
 673 Redirect the virtual parallel port to host device <VAR>dev</VAR> (same
 674 devices as the serial port). On Linux hosts, <TT>`/dev/parportN'</TT> can
 675 be used to use hardware devices connected on the corresponding host
 676 parallel port.
 677
 678 This option can be used several times to simulate up to 3 parallel
 679 ports.
 680
 681 <DT><SAMP>`-monitor dev'</SAMP>
 682 <DD>
 683 Redirect the monitor to host device <VAR>dev</VAR> (same devices as the
 684 serial port).
 685 The default device is <CODE>vc</CODE> in graphical mode and <CODE>stdio</CODE> in
 686 non graphical mode.
 687
 688 <DT><SAMP>`-s'</SAMP>
 689 <DD>
 690 Wait gdb connection to port 1234 (See section <A HREF="qemu-doc.html#SEC29">3.10 GDB usage</A>).
 691 <DT><SAMP>`-p port'</SAMP>
 692 <DD>
 693 Change gdb connection port.
 694 <DT><SAMP>`-S'</SAMP>
 695 <DD>
 696 Do not start CPU at startup (you must type 'c' in the monitor).
 697 <DT><SAMP>`-d'</SAMP>
 698 <DD>
 699 Output log in /tmp/qemu.log
 700 <DT><SAMP>`-hdachs c,h,s,[,t]'</SAMP>
 701 <DD>
 702 Force hard disk 0 physical geometry (1 &#60;= <VAR>c</VAR> &#60;= 16383, 1 &#60;=
 703 <VAR>h</VAR> &#60;= 16, 1 &#60;= <VAR>s</VAR> &#60;= 63) and optionally force the BIOS
 704 translation mode (<VAR>t</VAR>=none, lba or auto). Usually QEMU can guess
 705 all thoses parameters. This option is useful for old MS-DOS disk
 706 images.
 707
 708 <DT><SAMP>`-std-vga'</SAMP>
 709 <DD>
 710 Simulate a standard VGA card with Bochs VBE extensions (default is
 711 Cirrus Logic GD5446 PCI VGA)
 712 <DT><SAMP>`-loadvm file'</SAMP>
 713 <DD>
 714 Start right away with a saved state (<CODE>loadvm</CODE> in monitor)
 715 </DL>
 716
 717
 718
 719 <H2><A NAME="SEC11" HREF="qemu-doc.html#TOC11">3.4 Keys</A></H2>
 720
 721 <P>
 722 During the graphical emulation, you can use the following keys:
 723 <DL COMPACT>
 724
 725 <DT><KBD>Ctrl-Alt-f</KBD>
 726 <DD>
 727 Toggle full screen
 728
 729 <DT><KBD>Ctrl-Alt-n</KBD>
 730 <DD>
 731 Switch to virtual console 'n'. Standard console mappings are:
 732 <DL COMPACT>
 733
 734 <DT><EM>1</EM>
 735 <DD>
 736 Target system display
 737 <DT><EM>2</EM>
 738 <DD>
 739 Monitor
 740 <DT><EM>3</EM>
 741 <DD>
 742 Serial port
 743 </DL>
 744
 745 <DT><KBD>Ctrl-Alt</KBD>
 746 <DD>
 747 Toggle mouse and keyboard grab.
 748 </DL>
 749
 750 <P>
 751 In the virtual consoles, you can use <KBD>Ctrl-Up</KBD>, <KBD>Ctrl-Down</KBD>,
 752 <KBD>Ctrl-PageUp</KBD> and <KBD>Ctrl-PageDown</KBD> to move in the back log.
 753
 754
 755 <P>
 756 During emulation, if you are using the <SAMP>`-nographic'</SAMP> option, use
 757 <KBD>Ctrl-a h</KBD> to get terminal commands:
 758
 759
 760 <DL COMPACT>
 761
 762 <DT><KBD>Ctrl-a h</KBD>
 763 <DD>
 764 Print this help
 765 <DT><KBD>Ctrl-a x</KBD>
 766 <DD>
 767 Exit emulatior
 768 <DT><KBD>Ctrl-a s</KBD>
 769 <DD>
 770 Save disk data back to file (if -snapshot)
 771 <DT><KBD>Ctrl-a b</KBD>
 772 <DD>
 773 Send break (magic sysrq in Linux)
 774 <DT><KBD>Ctrl-a c</KBD>
 775 <DD>
 776 Switch between console and monitor
 777 <DT><KBD>Ctrl-a Ctrl-a</KBD>
 778 <DD>
 779 Send Ctrl-a
 780 </DL>
 781
 782
 783
 784 <H2><A NAME="SEC12" HREF="qemu-doc.html#TOC12">3.5 QEMU Monitor</A></H2>
 785
 786 <P>
 787 The QEMU monitor is used to give complex commands to the QEMU
 788 emulator. You can use it to:
 789
 790
 791
 792 <UL>
 793
 794 <LI>
 795
 796 Remove or insert removable medias images
 797 (such as CD-ROM or floppies)
 798
 799 <LI>
 800
 801 Freeze/unfreeze the Virtual Machine (VM) and save or restore its state
 802 from a disk file.
 803
 804 <LI>Inspect the VM state without an external debugger.
 805
 806 </UL>
 807
 808
 809
 810 <H3><A NAME="SEC13" HREF="qemu-doc.html#TOC13">3.5.1 Commands</A></H3>
 811
 812 <P>
 813 The following commands are available:
 814
 815
 816 <DL COMPACT>
 817
 818 <DT><SAMP>`help or ? [cmd]'</SAMP>
 819 <DD>
 820 Show the help for all commands or just for command <VAR>cmd</VAR>.
 821
 822 <DT><SAMP>`commit'</SAMP>
 823 <DD>
 824 Commit changes to the disk images (if -snapshot is used)
 825
 826 <DT><SAMP>`info subcommand'</SAMP>
 827 <DD>
 828 show various information about the system state
 829
 830 <DL COMPACT>
 831
 832 <DT><SAMP>`info network'</SAMP>
 833 <DD>
 834 show the various VLANs and the associated devices
 835 <DT><SAMP>`info block'</SAMP>
 836 <DD>
 837 show the block devices
 838 <DT><SAMP>`info registers'</SAMP>
 839 <DD>
 840 show the cpu registers
 841 <DT><SAMP>`info history'</SAMP>
 842 <DD>
 843 show the command line history
 844 <DT><SAMP>`info pci'</SAMP>
 845 <DD>
 846 show emulated PCI device
 847 <DT><SAMP>`info usb'</SAMP>
 848 <DD>
 849 show USB devices plugged on the virtual USB hub
 850 <DT><SAMP>`info usbhost'</SAMP>
 851 <DD>
 852 show all USB host devices
 853 </DL>
 854
 855 <DT><SAMP>`q or quit'</SAMP>
 856 <DD>
 857 Quit the emulator.
 858
 859 <DT><SAMP>`eject [-f] device'</SAMP>
 860 <DD>
 861 Eject a removable media (use -f to force it).
 862
 863 <DT><SAMP>`change device filename'</SAMP>
 864 <DD>
 865 Change a removable media.
 866
 867 <DT><SAMP>`screendump filename'</SAMP>
 868 <DD>
 869 Save screen into PPM image <VAR>filename</VAR>.
 870
 871 <DT><SAMP>`log item1[,...]'</SAMP>
 872 <DD>
 873 Activate logging of the specified items to <TT>`/tmp/qemu.log'</TT>.
 874
 875 <DT><SAMP>`savevm filename'</SAMP>
 876 <DD>
 877 Save the whole virtual machine state to <VAR>filename</VAR>.
 878
 879 <DT><SAMP>`loadvm filename'</SAMP>
 880 <DD>
 881 Restore the whole virtual machine state from <VAR>filename</VAR>.
 882
 883 <DT><SAMP>`stop'</SAMP>
 884 <DD>
 885 Stop emulation.
 886
 887 <DT><SAMP>`c or cont'</SAMP>
 888 <DD>
 889 Resume emulation.
 890
 891 <DT><SAMP>`gdbserver [port]'</SAMP>
 892 <DD>
 893 Start gdbserver session (default port=1234)
 894
 895 <DT><SAMP>`x/fmt addr'</SAMP>
 896 <DD>
 897 Virtual memory dump starting at <VAR>addr</VAR>.
 898
 899 <DT><SAMP>`xp /fmt addr'</SAMP>
 900 <DD>
 901 Physical memory dump starting at <VAR>addr</VAR>.
 902
 903 <VAR>fmt</VAR> is a format which tells the command how to format the
 904 data. Its syntax is: <SAMP>`/{count}{format}{size}'</SAMP>
 905
 906 <DL COMPACT>
 907
 908 <DT><VAR>count</VAR>
 909 <DD>
 910 is the number of items to be dumped.
 911
 912 <DT><VAR>format</VAR>
 913 <DD>
 914 can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal),
 915 c (char) or i (asm instruction).
 916
 917 <DT><VAR>size</VAR>
 918 <DD>
 919 can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86,
 920 <CODE>h</CODE> or <CODE>w</CODE> can be specified with the <CODE>i</CODE> format to
 921 respectively select 16 or 32 bit code instruction size.
 922
 923 </DL>
 924
 925 Examples:
 926
 927 <UL>
 928 <LI>
 929
 930 Dump 10 instructions at the current instruction pointer:
 931
 932 <PRE>
 933 (qemu) x/10i $eip
 934 0x90107063:  ret
 935 0x90107064:  sti
 936 0x90107065:  lea    0x0(%esi,1),%esi
 937 0x90107069:  lea    0x0(%edi,1),%edi
 938 0x90107070:  ret
 939 0x90107071:  jmp    0x90107080
 940 0x90107073:  nop
 941 0x90107074:  nop
 942 0x90107075:  nop
 943 0x90107076:  nop
 944 </PRE>
 945
 946 <LI>
 947
 948 Dump 80 16 bit values at the start of the video memory.
 949
 950 <PRE>
 951 (qemu) xp/80hx 0xb8000
 952 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42
 953 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41
 954 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72
 955 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73
 956 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20
 957 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720
 958 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 959 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 960 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 961 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720
 962 </PRE>
 963
 964 </UL>
 965
 966 <DT><SAMP>`p or print/fmt expr'</SAMP>
 967 <DD>
 968 Print expression value. Only the <VAR>format</VAR> part of <VAR>fmt</VAR> is
 969 used.
 970
 971 <DT><SAMP>`sendkey keys'</SAMP>
 972 <DD>
 973 Send <VAR>keys</VAR> to the emulator. Use <CODE>-</CODE> to press several keys
 974 simultaneously. Example:
 975
 976 <PRE>
 977 sendkey ctrl-alt-f1
 978 </PRE>
 979
 980 This command is useful to send keys that your graphical user interface
 981 intercepts at low level, such as <CODE>ctrl-alt-f1</CODE> in X Window.
 982
 983 <DT><SAMP>`system_reset'</SAMP>
 984 <DD>
 985 Reset the system.
 986
 987 <DT><SAMP>`usb_add devname'</SAMP>
 988 <DD>
 989 Plug the USB device devname to the QEMU virtual USB hub. <VAR>devname</VAR>
 990 is either a virtual device name (for example <CODE>mouse</CODE>) or a host
 991 USB device identifier. Host USB device identifiers have the following
 992 syntax: <CODE>host:bus.addr</CODE> or <CODE>host:vendor_id:product_id</CODE>.
 993
 994 <DT><SAMP>`usb_del devname'</SAMP>
 995 <DD>
 996 Remove the USB device <VAR>devname</VAR> from the QEMU virtual USB
 997 hub. <VAR>devname</VAR> has the syntax <CODE>bus.addr</CODE>. Use the monitor
 998 command <CODE>info usb</CODE> to see the devices you can remove.
 999
1000 </DL>
1001
1002
1003
1004 <H3><A NAME="SEC14" HREF="qemu-doc.html#TOC14">3.5.2 Integer expressions</A></H3>
1005
1006 <P>
1007 The monitor understands integers expressions for every integer
1008 argument. You can use register names to get the value of specifics
1009 CPU registers by prefixing them with <EM>$</EM>.
1010
1011
1012
1013
1014 <H2><A NAME="SEC15" HREF="qemu-doc.html#TOC15">3.6 Disk Images</A></H2>
1015
1016 <P>
1017 Since version 0.6.1, QEMU supports many disk image formats, including
1018 growable disk images (their size increase as non empty sectors are
1019 written), compressed and encrypted disk images.
1020
1021
1022
1023
1024 <H3><A NAME="SEC16" HREF="qemu-doc.html#TOC16">3.6.1 Quick start for disk image creation</A></H3>
1025
1026 <P>
1027 You can create a disk image with the command:
1028
1029 <PRE>
1030 qemu-img create myimage.img mysize
1031 </PRE>
1032
1033 <P>
1034 where <VAR>myimage.img</VAR> is the disk image filename and <VAR>mysize</VAR> is its
1035 size in kilobytes. You can add an <CODE>M</CODE> suffix to give the size in
1036 megabytes and a <CODE>G</CODE> suffix for gigabytes.
1037
1038
1039 <P>
1040 See section <A HREF="qemu-doc.html#SEC18">3.6.3 <CODE>qemu-img</CODE> Invocation</A> for more information.
1041
1042
1043
1044
1045 <H3><A NAME="SEC17" HREF="qemu-doc.html#TOC17">3.6.2 Snapshot mode</A></H3>
1046
1047 <P>
1048 If you use the option <SAMP>`-snapshot'</SAMP>, all disk images are
1049 considered as read only. When sectors in written, they are written in
1050 a temporary file created in <TT>`/tmp'</TT>. You can however force the
1051 write back to the raw disk images by using the <CODE>commit</CODE> monitor
1052 command (or <KBD>C-a s</KBD> in the serial console).
1053
1054
1055
1056
1057 <H3><A NAME="SEC18" HREF="qemu-doc.html#TOC18">3.6.3 <CODE>qemu-img</CODE> Invocation</A></H3>
1058
1059
1060 <PRE>
1061 usage: qemu-img command [command options]
1062 </PRE>
1063
1064 <P>
1065 The following commands are supported:
1066 <DL COMPACT>
1067
1068 <DT><SAMP>`create [-e] [-b <VAR>base_image</VAR>] [-f <VAR>fmt</VAR>] <VAR>filename</VAR> [<VAR>size</VAR>]'</SAMP>
1069 <DD>
1070 <DT><SAMP>`commit [-f <VAR>fmt</VAR>] <VAR>filename</VAR>'</SAMP>
1071 <DD>
1072 <DT><SAMP>`convert [-c] [-e] [-f <VAR>fmt</VAR>] <VAR>filename</VAR> [-O <VAR>output_fmt</VAR>] <VAR>output_filename</VAR>'</SAMP>
1073 <DD>
1074 <DT><SAMP>`info [-f <VAR>fmt</VAR>] <VAR>filename</VAR>'</SAMP>
1075 <DD>
1076 </DL>
1077
1078 <P>
1079 Command parameters:
1080 <DL COMPACT>
1081
1082 <DT><VAR>filename</VAR>
1083 <DD>
1084  is a disk image filename
1085 <DT><VAR>base_image</VAR>
1086 <DD>
1087 is the read-only disk image which is used as base for a copy on
1088     write image; the copy on write image only stores the modified data
1089
1090 <DT><VAR>fmt</VAR>
1091 <DD>
1092 is the disk image format. It is guessed automatically in most cases. The following formats are supported:
1093
1094 <DL COMPACT>
1095
1096 <DT><CODE>raw</CODE>
1097 <DD>
1098 Raw disk image format (default). This format has the advantage of
1099 being simple and easily exportable to all other emulators. If your file
1100 system supports <EM>holes</EM> (for example in ext2 or ext3 on Linux),
1101 then only the written sectors will reserve space. Use <CODE>qemu-img
1102 info</CODE> to know the real size used by the image or <CODE>ls -ls</CODE> on
1103 Unix/Linux.
1104
1105 <DT><CODE>qcow</CODE>
1106 <DD>
1107 QEMU image format, the most versatile format. Use it to have smaller
1108 images (useful if your filesystem does not supports holes, for example
1109 on Windows), optional AES encryption and zlib based compression.
1110 <DT><CODE>cow</CODE>
1111 <DD>
1112 User Mode Linux Copy On Write image format. Used to be the only growable
1113 image format in QEMU. It is supported only for compatibility with
1114 previous versions. It does not work on win32.
1115 <DT><CODE>vmdk</CODE>
1116 <DD>
1117 VMware 3 and 4 compatible image format.
1118 <DT><CODE>cloop</CODE>
1119 <DD>
1120 Linux Compressed Loop image, useful only to reuse directly compressed
1121 CD-ROM images present for example in the Knoppix CD-ROMs.
1122 </DL>
1123
1124 <DT><VAR>size</VAR>
1125 <DD>
1126 is the disk image size in kilobytes. Optional suffixes <CODE>M</CODE>
1127 (megabyte) and <CODE>G</CODE> (gigabyte) are supported
1128
1129 <DT><VAR>output_filename</VAR>
1130 <DD>
1131 is the destination disk image filename
1132
1133 <DT><VAR>output_fmt</VAR>
1134 <DD>
1135  is the destination format
1136
1137 <DT><VAR>-c</VAR>
1138 <DD>
1139 indicates that target image must be compressed (qcow format only)
1140 <DT><VAR>-e</VAR>
1141 <DD>
1142 indicates that the target image must be encrypted (qcow format only)
1143 </DL>
1144
1145 <P>
1146 Command description:
1147
1148
1149 <DL COMPACT>
1150
1151 <DT><SAMP>`create [-e] [-b <VAR>base_image</VAR>] [-f <VAR>fmt</VAR>] <VAR>filename</VAR> [<VAR>size</VAR>]'</SAMP>
1152 <DD>
1153 Create the new disk image <VAR>filename</VAR> of size <VAR>size</VAR> and format
1154 <VAR>fmt</VAR>.
1155
1156 If <VAR>base_image</VAR> is specified, then the image will record only the
1157 differences from <VAR>base_image</VAR>. No size needs to be specified in
1158 this case. <VAR>base_image</VAR> will never be modified unless you use the
1159 <CODE>commit</CODE> monitor command.
1160
1161 <DT><SAMP>`commit [-f <VAR>fmt</VAR>] <VAR>filename</VAR>'</SAMP>
1162 <DD>
1163 Commit the changes recorded in <VAR>filename</VAR> in its base image.
1164
1165 <DT><SAMP>`convert [-c] [-e] [-f <VAR>fmt</VAR>] <VAR>filename</VAR> [-O <VAR>output_fmt</VAR>] <VAR>output_filename</VAR>'</SAMP>
1166 <DD>
1167 Convert the disk image <VAR>filename</VAR> to disk image <VAR>output_filename</VAR>
1168 using format <VAR>output_fmt</VAR>. It can be optionnaly encrypted
1169 (<CODE>-e</CODE> option) or compressed (<CODE>-c</CODE> option).
1170
1171 Only the format <CODE>qcow</CODE> supports encryption or compression. The
1172 compression is read-only. It means that if a compressed sector is
1173 rewritten, then it is rewritten as uncompressed data.
1174
1175 Encryption uses the AES format which is very secure (128 bit keys). Use
1176 a long password (16 characters) to get maximum protection.
1177
1178 Image conversion is also useful to get smaller image when using a
1179 growable format such as <CODE>qcow</CODE> or <CODE>cow</CODE>: the empty sectors
1180 are detected and suppressed from the destination image.
1181
1182 <DT><SAMP>`info [-f <VAR>fmt</VAR>] <VAR>filename</VAR>'</SAMP>
1183 <DD>
1184 Give information about the disk image <VAR>filename</VAR>. Use it in
1185 particular to know the size reserved on disk which can be different
1186 from the displayed size.
1187 </DL>
1188
1189
1190
1191 <H3><A NAME="SEC19" HREF="qemu-doc.html#TOC19">3.6.4 Virtual FAT disk images</A></H3>
1192
1193 <P>
1194 QEMU can automatically create a virtual FAT disk image from a
1195 directory tree. In order to use it, just type:
1196
1197
1198
1199 <PRE>
1200 qemu linux.img -hdb fat:/my_directory
1201 </PRE>
1202
1203 <P>
1204 Then you access access to all the files in the <TT>`/my_directory'</TT>
1205 directory without having to copy them in a disk image or to export
1206 them via SAMBA or NFS. The default access is <EM>read-only</EM>.
1207
1208
1209 <P>
1210 Floppies can be emulated with the <CODE>:floppy:</CODE> option:
1211
1212
1213
1214 <PRE>
1215 qemu linux.img -fda fat:floppy:/my_directory
1216 </PRE>
1217
1218 <P>
1219 A read/write support is available for testing (beta stage) with the
1220 <CODE>:rw:</CODE> option:
1221
1222
1223
1224 <PRE>
1225 qemu linux.img -fda fat:floppy:rw:/my_directory
1226 </PRE>
1227
1228 <P>
1229 What you should <EM>never</EM> do:
1230
1231 <UL>
1232 <LI>use non-ASCII filenames ;
1233
1234 <LI>use "-snapshot" together with ":rw:" ;
1235
1236 <LI>expect it to work when loadvm'ing ;
1237
1238 <LI>write to the FAT directory on the host system while accessing it with the guest system.
1239
1240 </UL>
1241
1242
1243
1244 <H2><A NAME="SEC20" HREF="qemu-doc.html#TOC20">3.7 Network emulation</A></H2>
1245
1246 <P>
1247 QEMU can simulate several networks cards (NE2000 boards on the PC
1248 target) and can connect them to an arbitrary number of Virtual Local
1249 Area Networks (VLANs). Host TAP devices can be connected to any QEMU
1250 VLAN. VLAN can be connected between separate instances of QEMU to
1251 simulate large networks. For simpler usage, a non priviledged user mode
1252 network stack can replace the TAP device to have a basic network
1253 connection.
1254
1255
1256
1257
1258 <H3><A NAME="SEC21" HREF="qemu-doc.html#TOC21">3.7.1 VLANs</A></H3>
1259
1260 <P>
1261 QEMU simulates several VLANs. A VLAN can be symbolised as a virtual
1262 connection between several network devices. These devices can be for
1263 example QEMU virtual Ethernet cards or virtual Host ethernet devices
1264 (TAP devices).
1265
1266
1267
1268
1269 <H3><A NAME="SEC22" HREF="qemu-doc.html#TOC22">3.7.2 Using TAP network interfaces</A></H3>
1270
1271 <P>
1272 This is the standard way to connect QEMU to a real network. QEMU adds
1273 a virtual network device on your host (called <CODE>tapN</CODE>), and you
1274 can then configure it as if it was a real ethernet card.
1275
1276
1277 <P>
1278 As an example, you can download the <TT>`linux-test-xxx.tar.gz'</TT>
1279 archive and copy the script <TT>`qemu-ifup'</TT> in <TT>`/etc'</TT> and
1280 configure properly <CODE>sudo</CODE> so that the command <CODE>ifconfig</CODE>
1281 contained in <TT>`qemu-ifup'</TT> can be executed as root. You must verify
1282 that your host kernel supports the TAP network interfaces: the
1283 device <TT>`/dev/net/tun'</TT> must be present.
1284
1285
1286 <P>
1287 See section <A HREF="qemu-doc.html#SEC25">3.8 Direct Linux Boot</A> to have an example of network use with a
1288 Linux distribution and section <A HREF="qemu-doc.html#SEC10">3.3 Invocation</A> to have examples of
1289 command lines using the TAP network interfaces.
1290
1291
1292
1293
1294 <H3><A NAME="SEC23" HREF="qemu-doc.html#TOC23">3.7.3 Using the user mode network stack</A></H3>
1295
1296 <P>
1297 By using the option <SAMP>`-net user'</SAMP> (default configuration if no
1298 <SAMP>`-net'</SAMP> option is specified), QEMU uses a completely user mode
1299 network stack (you don't need root priviledge to use the virtual
1300 network). The virtual network configuration is the following:
1301
1302
1303
1304 <PRE>
1305
1306          QEMU VLAN      &#60;------&#62;  Firewall/DHCP server &#60;-----&#62; Internet
1307                            |          (10.0.2.2)
1308                            |
1309                            ----&#62;  DNS server (10.0.2.3)
1310                            |
1311                            ----&#62;  SMB server (10.0.2.4)
1312 </PRE>
1313
1314 <P>
1315 The QEMU VM behaves as if it was behind a firewall which blocks all
1316 incoming connections. You can use a DHCP client to automatically
1317 configure the network in the QEMU VM. The DHCP server assign addresses
1318 to the hosts starting from 10.0.2.15.
1319
1320
1321 <P>
1322 In order to check that the user mode network is working, you can ping
1323 the address 10.0.2.2 and verify that you got an address in the range
1324 10.0.2.x from the QEMU virtual DHCP server.
1325
1326
1327 <P>
1328 Note that <CODE>ping</CODE> is not supported reliably to the internet as it
1329 would require root priviledges. It means you can only ping the local
1330 router (10.0.2.2).
1331
1332
1333 <P>
1334 When using the built-in TFTP server, the router is also the TFTP
1335 server.
1336
1337
1338 <P>
1339 When using the <SAMP>`-redir'</SAMP> option, TCP or UDP connections can be
1340 redirected from the host to the guest. It allows for example to
1341 redirect X11, telnet or SSH connections.
1342
1343
1344
1345
1346 <H3><A NAME="SEC24" HREF="qemu-doc.html#TOC24">3.7.4 Connecting VLANs between QEMU instances</A></H3>
1347
1348 <P>
1349 Using the <SAMP>`-net socket'</SAMP> option, it is possible to make VLANs
1350 that span several QEMU instances. See section <A HREF="qemu-doc.html#SEC10">3.3 Invocation</A> to have a
1351 basic example.
1352
1353
1354
1355
1356 <H2><A NAME="SEC25" HREF="qemu-doc.html#TOC25">3.8 Direct Linux Boot</A></H2>
1357
1358 <P>
1359 This section explains how to launch a Linux kernel inside QEMU without
1360 having to make a full bootable image. It is very useful for fast Linux
1361 kernel testing. The QEMU network configuration is also explained.
1362
1363
1364
1365 <OL>
1366 <LI>
1367
1368 Download the archive <TT>`linux-test-xxx.tar.gz'</TT> containing a Linux
1369 kernel and a disk image.
1370
1371 <LI>Optional: If you want network support (for example to launch X11 examples), you
1372
1373 must copy the script <TT>`qemu-ifup'</TT> in <TT>`/etc'</TT> and configure
1374 properly <CODE>sudo</CODE> so that the command <CODE>ifconfig</CODE> contained in
1375 <TT>`qemu-ifup'</TT> can be executed as root. You must verify that your host
1376 kernel supports the TUN/TAP network interfaces: the device
1377 <TT>`/dev/net/tun'</TT> must be present.
1378
1379 When network is enabled, there is a virtual network connection between
1380 the host kernel and the emulated kernel. The emulated kernel is seen
1381 from the host kernel at IP address 172.20.0.2 and the host kernel is
1382 seen from the emulated kernel at IP address 172.20.0.1.
1383
1384 <LI>Launch <CODE>qemu.sh</CODE>. You should have the following output:
1385
1386
1387 <PRE>
1388 &#62; ./qemu.sh
1389 Connected to host network interface: tun0
1390 Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
1391 BIOS-provided physical RAM map:
1392  BIOS-e801: 0000000000000000 - 000000000009f000 (usable)
1393  BIOS-e801: 0000000000100000 - 0000000002000000 (usable)
1394 32MB LOWMEM available.
1395 On node 0 totalpages: 8192
1396 zone(0): 4096 pages.
1397 zone(1): 4096 pages.
1398 zone(2): 0 pages.
1399 Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0
1400 ide_setup: ide2=noprobe
1401 ide_setup: ide3=noprobe
1402 ide_setup: ide4=noprobe
1403 ide_setup: ide5=noprobe
1404 Initializing CPU#0
1405 Detected 2399.621 MHz processor.
1406 Console: colour EGA 80x25
1407 Calibrating delay loop... 4744.80 BogoMIPS
1408 Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem)
1409 Dentry cache hash table entries: 4096 (order: 3, 32768 bytes)
1410 Inode cache hash table entries: 2048 (order: 2, 16384 bytes)
1411 Mount cache hash table entries: 512 (order: 0, 4096 bytes)
1412 Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)
1413 Page-cache hash table entries: 8192 (order: 3, 32768 bytes)
1414 CPU: Intel Pentium Pro stepping 03
1415 Checking 'hlt' instruction... OK.
1416 POSIX conformance testing by UNIFIX
1417 Linux NET4.0 for Linux 2.4
1418 Based upon Swansea University Computer Society NET3.039
1419 Initializing RT netlink socket
1420 apm: BIOS not found.
1421 Starting kswapd
1422 Journalled Block Device driver loaded
1423 Detected PS/2 Mouse Port.
1424 pty: 256 Unix98 ptys configured
1425 Serial driver version 5.05c (2001-07-08) with no serial options enabled
1426 ttyS00 at 0x03f8 (irq = 4) is a 16450
1427 ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com)
1428 Last modified Nov 1, 2000 by Paul Gortmaker
1429 NE*000 ethercard probe at 0x300: 52 54 00 12 34 56
1430 eth0: NE2000 found at 0x300, using IRQ 9.
1431 RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize
1432 Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4
1433 ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx
1434 hda: QEMU HARDDISK, ATA DISK drive
1435 ide0 at 0x1f0-0x1f7,0x3f6 on irq 14
1436 hda: attached ide-disk driver.
1437 hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63
1438 Partition check:
1439  hda:
1440 Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996
1441 NET4: Linux TCP/IP 1.0 for NET4.0
1442 IP Protocols: ICMP, UDP, TCP, IGMP
1443 IP: routing cache hash table of 512 buckets, 4Kbytes
1444 TCP: Hash tables configured (established 2048 bind 4096)
1445 NET4: Unix domain sockets 1.0/SMP for Linux NET4.0.
1446 EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended
1447 VFS: Mounted root (ext2 filesystem).
1448 Freeing unused kernel memory: 64k freed
1449
1450 Linux version 2.4.21 (bellard@voyager.localdomain) (gcc version 3.2.2 20030222 (Red Hat Linux 3.2.2-5)) #5 Tue Nov 11 18:18:53 CET 2003
1451
1452 QEMU Linux test distribution (based on Redhat 9)
1453
1454 Type 'exit' to halt the system
1455
1456 sh-2.05b#
1457 </PRE>
1458
1459 <LI>
1460
1461 Then you can play with the kernel inside the virtual serial console. You
1462 can launch <CODE>ls</CODE> for example. Type <KBD>Ctrl-a h</KBD> to have an help
1463 about the keys you can type inside the virtual serial console. In
1464 particular, use <KBD>Ctrl-a x</KBD> to exit QEMU and use <KBD>Ctrl-a b</KBD> as
1465 the Magic SysRq key.
1466
1467 <LI>
1468
1469 If the network is enabled, launch the script <TT>`/etc/linuxrc'</TT> in the
1470 emulator (don't forget the leading dot):
1471
1472 <PRE>
1473 . /etc/linuxrc
1474 </PRE>
1475
1476 Then enable X11 connections on your PC from the emulated Linux:
1477
1478 <PRE>
1479 xhost +172.20.0.2
1480 </PRE>
1481
1482 You can now launch <TT>`xterm'</TT> or <TT>`xlogo'</TT> and verify that you have
1483 a real Virtual Linux system !
1484
1485 </OL>
1486
1487 <P>
1488 NOTES:
1489
1490 <OL>
1491 <LI>
1492
1493 A 2.5.74 kernel is also included in the archive. Just
1494 replace the bzImage in qemu.sh to try it.
1495
1496 <LI>
1497
1498 In order to exit cleanly from qemu, you can do a <EM>shutdown</EM> inside
1499 qemu. qemu will automatically exit when the Linux shutdown is done.
1500
1501 <LI>
1502
1503 You can boot slightly faster by disabling the probe of non present IDE
1504 interfaces. To do so, add the following options on the kernel command
1505 line:
1506
1507 <PRE>
1508 ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe
1509 </PRE>
1510
1511 <LI>
1512
1513 The example disk image is a modified version of the one made by Kevin
1514 Lawton for the plex86 Project (<A HREF="www.plex86.org">www.plex86.org</A>).
1515
1516 </OL>
1517
1518
1519
1520 <H2><A NAME="SEC26" HREF="qemu-doc.html#TOC26">3.9 USB emulation</A></H2>
1521
1522 <P>
1523 QEMU emulates a PCI UHCI USB controller and a 8 port USB hub connected
1524 to it. You can virtually plug to the hub virtual USB devices or real
1525 host USB devices (experimental, works only on Linux hosts).
1526
1527
1528
1529
1530 <H3><A NAME="SEC27" HREF="qemu-doc.html#TOC27">3.9.1 Using virtual USB devices</A></H3>
1531
1532 <P>
1533 A virtual USB mouse device is available for testing in QEMU.
1534
1535
1536 <P>
1537 You can try it with the following monitor commands:
1538
1539
1540
1541 <PRE>
1542 # add the mouse device
1543 (qemu) usb_add mouse
1544
1545 # show the virtual USB devices plugged on the QEMU Virtual USB hub
1546 (qemu) info usb
1547   Device 0.3, speed 12 Mb/s
1548
1549 # after some time you can try to remove the mouse
1550 (qemu) usb_del 0.3
1551 </PRE>
1552
1553 <P>
1554 The option <SAMP>`-usbdevice'</SAMP> is similar to the monitor command
1555 <CODE>usb_add</CODE>.
1556
1557
1558
1559
1560 <H3><A NAME="SEC28" HREF="qemu-doc.html#TOC28">3.9.2 Using host USB devices on a Linux host</A></H3>
1561
1562 <P>
1563 WARNING: this is an experimental feature. QEMU will slow down when
1564 using it. USB devices requiring real time streaming (i.e. USB Video
1565 Cameras) are not supported yet.
1566
1567
1568
1569 <OL>
1570 <LI>If you use an early Linux 2.4 kernel, verify that no Linux driver
1571
1572 is actually using the USB device. A simple way to do that is simply to
1573 disable the corresponding kernel module by renaming it from <TT>`mydriver.o'</TT>
1574 to <TT>`mydriver.o.disabled'</TT>.
1575
1576 <LI>Verify that <TT>`/proc/bus/usb'</TT> is working (most Linux distributions should enable it by default). You should see something like that:
1577
1578
1579 <PRE>
1580 ls /proc/bus/usb
1581 001  devices  drivers
1582 </PRE>
1583
1584 <LI>Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices:
1585
1586
1587 <PRE>
1588 chown -R myuid /proc/bus/usb
1589 </PRE>
1590
1591 <LI>Launch QEMU and do in the monitor:
1592
1593
1594 <PRE>
1595 info usbhost
1596   Device 1.2, speed 480 Mb/s
1597     Class 00: USB device 1234:5678, USB DISK
1598 </PRE>
1599
1600 You should see the list of the devices you can use (Never try to use
1601 hubs, it won't work).
1602
1603 <LI>Add the device in QEMU by using:
1604
1605
1606 <PRE>
1607 usb_add host:1234:5678
1608 </PRE>
1609
1610 Normally the guest OS should report that a new USB device is
1611 plugged. You can use the option <SAMP>`-usbdevice'</SAMP> to do the same.
1612
1613 <LI>Now you can try to use the host USB device in QEMU.
1614
1615 </OL>
1616
1617 <P>
1618 When relaunching QEMU, you may have to unplug and plug again the USB
1619 device to make it work again (this is a bug).
1620
1621
1622
1623
1624 <H2><A NAME="SEC29" HREF="qemu-doc.html#TOC29">3.10 GDB usage</A></H2>
1625
1626 <P>
1627 QEMU has a primitive support to work with gdb, so that you can do
1628 'Ctrl-C' while the virtual machine is running and inspect its state.
1629
1630
1631 <P>
1632 In order to use gdb, launch qemu with the '-s' option. It will wait for a
1633 gdb connection:
1634
1635 <PRE>
1636 &#62; qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda"
1637 Connected to host network interface: tun0
1638 Waiting gdb connection on port 1234
1639 </PRE>
1640
1641 <P>
1642 Then launch gdb on the 'vmlinux' executable:
1643
1644 <PRE>
1645 &#62; gdb vmlinux
1646 </PRE>
1647
1648 <P>
1649 In gdb, connect to QEMU:
1650
1651 <PRE>
1652 (gdb) target remote localhost:1234
1653 </PRE>
1654
1655 <P>
1656 Then you can use gdb normally. For example, type 'c' to launch the kernel:
1657
1658 <PRE>
1659 (gdb) c
1660 </PRE>
1661
1662 <P>
1663 Here are some useful tips in order to use gdb on system code:
1664
1665
1666
1667 <OL>
1668 <LI>
1669
1670 Use <CODE>info reg</CODE> to display all the CPU registers.
1671 <LI>
1672
1673 Use <CODE>x/10i $eip</CODE> to display the code at the PC position.
1674 <LI>
1675
1676 Use <CODE>set architecture i8086</CODE> to dump 16 bit code. Then use
1677 <CODE>x/10i $cs*16+*eip</CODE> to dump the code at the PC position.
1678 </OL>
1679
1680
1681
1682 <H2><A NAME="SEC30" HREF="qemu-doc.html#TOC30">3.11 Target OS specific information</A></H2>
1683
1684
1685
1686 <H3><A NAME="SEC31" HREF="qemu-doc.html#TOC31">3.11.1 Linux</A></H3>
1687
1688 <P>
1689 To have access to SVGA graphic modes under X11, use the <CODE>vesa</CODE> or
1690 the <CODE>cirrus</CODE> X11 driver. For optimal performances, use 16 bit
1691 color depth in the guest and the host OS.
1692
1693
1694 <P>
1695 When using a 2.6 guest Linux kernel, you should add the option
1696 <CODE>clock=pit</CODE> on the kernel command line because the 2.6 Linux
1697 kernels make very strict real time clock checks by default that QEMU
1698 cannot simulate exactly.
1699
1700
1701 <P>
1702 When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is
1703 not activated because QEMU is slower with this patch. The QEMU
1704 Accelerator Module is also much slower in this case. Earlier Fedora
1705 Core 3 Linux kernel (&#60; 2.6.9-1.724_FC3) were known to incorporte this
1706 patch by default. Newer kernels don't have it.
1707
1708
1709
1710
1711 <H3><A NAME="SEC32" HREF="qemu-doc.html#TOC32">3.11.2 Windows</A></H3>
1712
1713 <P>
1714 If you have a slow host, using Windows 95 is better as it gives the
1715 best speed. Windows 2000 is also a good choice.
1716
1717
1718
1719
1720 <H4><A NAME="SEC33" HREF="qemu-doc.html#TOC33">3.11.2.1 SVGA graphic modes support</A></H4>
1721
1722 <P>
1723 QEMU emulates a Cirrus Logic GD5446 Video
1724 card. All Windows versions starting from Windows 95 should recognize
1725 and use this graphic card. For optimal performances, use 16 bit color
1726 depth in the guest and the host OS.
1727
1728
1729
1730
1731 <H4><A NAME="SEC34" HREF="qemu-doc.html#TOC34">3.11.2.2 CPU usage reduction</A></H4>
1732
1733 <P>
1734 Windows 9x does not correctly use the CPU HLT
1735 instruction. The result is that it takes host CPU cycles even when
1736 idle. You can install the utility from
1737 <A HREF="http://www.user.cityline.ru/~maxamn/amnhltm.zip">http://www.user.cityline.ru/~maxamn/amnhltm.zip</A> to solve this
1738 problem. Note that no such tool is needed for NT, 2000 or XP.
1739
1740
1741
1742
1743 <H4><A NAME="SEC35" HREF="qemu-doc.html#TOC35">3.11.2.3 Windows 2000 disk full problem</A></H4>
1744
1745 <P>
1746 Windows 2000 has a bug which gives a disk full problem during its
1747 installation. When installing it, use the <SAMP>`-win2k-hack'</SAMP> QEMU
1748 option to enable a specific workaround. After Windows 2000 is
1749 installed, you no longer need this option (this option slows down the
1750 IDE transfers).
1751
1752
1753
1754
1755 <H4><A NAME="SEC36" HREF="qemu-doc.html#TOC36">3.11.2.4 Windows 2000 shutdown</A></H4>
1756
1757 <P>
1758 Windows 2000 cannot automatically shutdown in QEMU although Windows 98
1759 can. It comes from the fact that Windows 2000 does not automatically
1760 use the APM driver provided by the BIOS.
1761
1762
1763 <P>
1764 In order to correct that, do the following (thanks to Struan
1765 Bartlett): go to the Control Panel =&#62; Add/Remove Hardware &#38; Next =&#62;
1766 Add/Troubleshoot a device =&#62; Add a new device &#38; Next =&#62; No, select the
1767 hardware from a list &#38; Next =&#62; NT Apm/Legacy Support &#38; Next =&#62; Next
1768 (again) a few times. Now the driver is installed and Windows 2000 now
1769 correctly instructs QEMU to shutdown at the appropriate moment.
1770
1771
1772
1773
1774 <H4><A NAME="SEC37" HREF="qemu-doc.html#TOC37">3.11.2.5 Share a directory between Unix and Windows</A></H4>
1775
1776 <P>
1777 See section <A HREF="qemu-doc.html#SEC10">3.3 Invocation</A> about the help of the option <SAMP>`-smb'</SAMP>.
1778
1779
1780
1781
1782 <H4><A NAME="SEC38" HREF="qemu-doc.html#TOC38">3.11.2.6 Windows XP security problems</A></H4>
1783
1784 <P>
1785 Some releases of Windows XP install correctly but give a security
1786 error when booting:
1787
1788 <PRE>
1789 A problem is preventing Windows from accurately checking the
1790 license for this computer. Error code: 0x800703e6.
1791 </PRE>
1792
1793 <P>
1794 The only known workaround is to boot in Safe mode
1795 without networking support.
1796
1797
1798 <P>
1799 Future QEMU releases are likely to correct this bug.
1800
1801
1802
1803
1804 <H3><A NAME="SEC39" HREF="qemu-doc.html#TOC39">3.11.3 MS-DOS and FreeDOS</A></H3>
1805
1806
1807
1808 <H4><A NAME="SEC40" HREF="qemu-doc.html#TOC40">3.11.3.1 CPU usage reduction</A></H4>
1809
1810 <P>
1811 DOS does not correctly use the CPU HLT instruction. The result is that
1812 it takes host CPU cycles even when idle. You can install the utility
1813 from <A HREF="http://www.vmware.com/software/dosidle210.zip">http://www.vmware.com/software/dosidle210.zip</A> to solve this
1814 problem.
1815
1816
1817
1818
1819 <H1><A NAME="SEC41" HREF="qemu-doc.html#TOC41">4. QEMU System emulator for non PC targets</A></H1>
1820
1821 <P>
1822 QEMU is a generic emulator and it emulates many non PC
1823 machines. Most of the options are similar to the PC emulator. The
1824 differences are mentionned in the following sections.
1825
1826
1827
1828
1829 <H2><A NAME="SEC42" HREF="qemu-doc.html#TOC42">4.1 QEMU PowerPC System emulator</A></H2>
1830
1831 <P>
1832 Use the executable <TT>`qemu-system-ppc'</TT> to simulate a complete PREP
1833 or PowerMac PowerPC system.
1834
1835
1836 <P>
1837 QEMU emulates the following PowerMac peripherals:
1838
1839
1840
1841 <UL>
1842 <LI>
1843
1844 UniNorth PCI Bridge
1845 <LI>
1846
1847 PCI VGA compatible card with VESA Bochs Extensions
1848 <LI>
1849
1850 2 PMAC IDE interfaces with hard disk and CD-ROM support
1851 <LI>
1852
1853 NE2000 PCI adapters
1854 <LI>
1855
1856 Non Volatile RAM
1857 <LI>
1858
1859 VIA-CUDA with ADB keyboard and mouse.
1860 </UL>
1861
1862 <P>
1863 QEMU emulates the following PREP peripherals:
1864
1865
1866
1867 <UL>
1868 <LI>
1869
1870 PCI Bridge
1871 <LI>
1872
1873 PCI VGA compatible card with VESA Bochs Extensions
1874 <LI>
1875
1876 2 IDE interfaces with hard disk and CD-ROM support
1877 <LI>
1878
1879 Floppy disk
1880 <LI>
1881
1882 NE2000 network adapters
1883 <LI>
1884
1885 Serial port
1886 <LI>
1887
1888 PREP Non Volatile RAM
1889 <LI>
1890
1891 PC compatible keyboard and mouse.
1892 </UL>
1893
1894 <P>
1895 QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at
1896 <A HREF="http://perso.magic.fr/l_indien/OpenHackWare/index.htm">http://perso.magic.fr/l_indien/OpenHackWare/index.htm</A>.
1897
1898
1899 <P>
1900 The following options are specific to the PowerPC emulation:
1901
1902
1903 <DL COMPACT>
1904
1905 <DT><SAMP>`-g WxH[xDEPTH]'</SAMP>
1906 <DD>
1907 Set the initial VGA graphic mode. The default is 800x600x15.
1908
1909 </DL>
1910
1911 <P>
1912 More information is available at
1913 <A HREF="http://perso.magic.fr/l_indien/qemu-ppc/">http://perso.magic.fr/l_indien/qemu-ppc/</A>.
1914
1915
1916
1917
1918 <H2><A NAME="SEC43" HREF="qemu-doc.html#TOC43">4.2 Sparc32 System emulator invocation</A></H2>
1919
1920 <P>
1921 Use the executable <TT>`qemu-system-sparc'</TT> to simulate a JavaStation
1922 (sun4m architecture). The emulation is somewhat complete.
1923
1924
1925 <P>
1926 QEMU emulates the following sun4m peripherals:
1927
1928
1929
1930 <UL>
1931 <LI>
1932
1933 IOMMU
1934 <LI>
1935
1936 TCX Frame buffer
1937 <LI>
1938
1939 Lance (Am7990) Ethernet
1940 <LI>
1941
1942 Non Volatile RAM M48T08
1943 <LI>
1944
1945 Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard
1946 and power/reset logic
1947 <LI>
1948
1949 ESP SCSI controller with hard disk and CD-ROM support
1950 <LI>
1951
1952 Floppy drive
1953 </UL>
1954
1955 <P>
1956 The number of peripherals is fixed in the architecture.
1957
1958
1959 <P>
1960 QEMU uses the Proll, a PROM replacement available at
1961 <A HREF="http://people.redhat.com/zaitcev/linux/">http://people.redhat.com/zaitcev/linux/</A>. The required
1962 QEMU-specific patches are included with the sources.
1963
1964
1965 <P>
1966 A sample Linux 2.6 series kernel and ram disk image are available on
1967 the QEMU web site. Please note that currently neither Linux 2.4
1968 series, NetBSD, nor OpenBSD kernels work.
1969
1970
1971 <P>
1972 The following options are specific to the Sparc emulation:
1973
1974
1975 <DL COMPACT>
1976
1977 <DT><SAMP>`-g WxH'</SAMP>
1978 <DD>
1979 Set the initial TCX graphic mode. The default is 1024x768.
1980
1981 </DL>
1982
1983
1984
1985 <H2><A NAME="SEC44" HREF="qemu-doc.html#TOC44">4.3 Sparc64 System emulator invocation</A></H2>
1986
1987 <P>
1988 Use the executable <TT>`qemu-system-sparc64'</TT> to simulate a Sun4u machine.
1989 The emulator is not usable for anything yet.
1990
1991
1992 <P>
1993 QEMU emulates the following sun4u peripherals:
1994
1995
1996
1997 <UL>
1998 <LI>
1999
2000 UltraSparc IIi APB PCI Bridge
2001 <LI>
2002
2003 PCI VGA compatible card with VESA Bochs Extensions
2004 <LI>
2005
2006 Non Volatile RAM M48T59
2007 <LI>
2008
2009 PC-compatible serial ports
2010 </UL>
2011
2012
2013
2014 <H2><A NAME="SEC45" HREF="qemu-doc.html#TOC45">4.4 MIPS System emulator invocation</A></H2>
2015
2016 <P>
2017 Use the executable <TT>`qemu-system-mips'</TT> to simulate a MIPS machine.
2018 The emulator is able to boot a Linux kernel and to run a Linux Debian
2019 installation from NFS. The following devices are emulated:
2020
2021
2022
2023 <UL>
2024 <LI>
2025
2026 MIPS R4K CPU
2027 <LI>
2028
2029 PC style serial port
2030 <LI>
2031
2032 NE2000 network card
2033 </UL>
2034
2035 <P>
2036 More information is available in the QEMU mailing-list archive.
2037
2038
2039
2040
2041 <H2><A NAME="SEC46" HREF="qemu-doc.html#TOC46">4.5 ARM System emulator invocation</A></H2>
2042
2043 <P>
2044 Use the executable <TT>`qemu-system-arm'</TT> to simulate a ARM
2045 machine. The ARM Integrator/CP board is emulated with the following
2046 devices:
2047
2048
2049
2050 <UL>
2051 <LI>
2052
2053 ARM1026E CPU
2054 <LI>
2055
2056 Two PL011 UARTs
2057 <LI>
2058
2059 SMC 91c111 Ethernet adapter
2060 </UL>
2061
2062 <P>
2063 A Linux 2.6 test image is available on the QEMU web site. More
2064 information is available in the QEMU mailing-list archive.
2065
2066
2067
2068
2069 <H1><A NAME="SEC47" HREF="qemu-doc.html#TOC47">5. QEMU Linux User space emulator</A></H1>
2070
2071
2072
2073 <H2><A NAME="SEC48" HREF="qemu-doc.html#TOC48">5.1 Quick Start</A></H2>
2074
2075 <P>
2076 In order to launch a Linux process, QEMU needs the process executable
2077 itself and all the target (x86) dynamic libraries used by it.
2078
2079
2080
2081 <UL>
2082
2083 <LI>On x86, you can just try to launch any process by using the native
2084
2085 libraries:
2086
2087
2088 <PRE>
2089 qemu-i386 -L / /bin/ls
2090 </PRE>
2091
2092 <CODE>-L /</CODE> tells that the x86 dynamic linker must be searched with a
2093 <TT>`/'</TT> prefix.
2094
2095 <LI>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):
2096
2097
2098 <PRE>
2099 qemu-i386 -L / qemu-i386 -L / /bin/ls
2100 </PRE>
2101
2102 <LI>On non x86 CPUs, you need first to download at least an x86 glibc
2103
2104 (<TT>`qemu-runtime-i386-XXX-.tar.gz'</TT> on the QEMU web page). Ensure that
2105 <CODE>LD_LIBRARY_PATH</CODE> is not set:
2106
2107
2108 <PRE>
2109 unset LD_LIBRARY_PATH
2110 </PRE>
2111
2112 Then you can launch the precompiled <TT>`ls'</TT> x86 executable:
2113
2114
2115 <PRE>
2116 qemu-i386 tests/i386/ls
2117 </PRE>
2118
2119 You can look at <TT>`qemu-binfmt-conf.sh'</TT> so that
2120 QEMU is automatically launched by the Linux kernel when you try to
2121 launch x86 executables. It requires the <CODE>binfmt_misc</CODE> module in the
2122 Linux kernel.
2123
2124 <LI>The x86 version of QEMU is also included. You can try weird things such as:
2125
2126
2127 <PRE>
2128 qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2129 </PRE>
2130
2131 </UL>
2132
2133
2134
2135 <H2><A NAME="SEC49" HREF="qemu-doc.html#TOC49">5.2 Wine launch</A></H2>
2136
2137
2138 <UL>
2139
2140 <LI>Ensure that you have a working QEMU with the x86 glibc
2141
2142 distribution (see previous section). In order to verify it, you must be
2143 able to do:
2144
2145
2146 <PRE>
2147 qemu-i386 /usr/local/qemu-i386/bin/ls-i386
2148 </PRE>
2149
2150 <LI>Download the binary x86 Wine install
2151
2152 (<TT>`qemu-XXX-i386-wine.tar.gz'</TT> on the QEMU web page).
2153
2154 <LI>Configure Wine on your account. Look at the provided script
2155
2156 <TT>`/usr/local/qemu-i386/bin/wine-conf.sh'</TT>. Your previous
2157 <CODE>${HOME}/.wine</CODE> directory is saved to <CODE>${HOME}/.wine.org</CODE>.
2158
2159 <LI>Then you can try the example <TT>`putty.exe'</TT>:
2160
2161
2162 <PRE>
2163 qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe
2164 </PRE>
2165
2166 </UL>
2167
2168
2169
2170 <H2><A NAME="SEC50" HREF="qemu-doc.html#TOC50">5.3 Command line options</A></H2>
2171
2172
2173 <PRE>
2174 usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...]
2175 </PRE>
2176
2177 <DL COMPACT>
2178
2179 <DT><SAMP>`-h'</SAMP>
2180 <DD>
2181 Print the help
2182 <DT><SAMP>`-L path'</SAMP>
2183 <DD>
2184 Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386)
2185 <DT><SAMP>`-s size'</SAMP>
2186 <DD>
2187 Set the x86 stack size in bytes (default=524288)
2188 </DL>
2189
2190 <P>
2191 Debug options:
2192
2193
2194 <DL COMPACT>
2195
2196 <DT><SAMP>`-d'</SAMP>
2197 <DD>
2198 Activate log (logfile=/tmp/qemu.log)
2199 <DT><SAMP>`-p pagesize'</SAMP>
2200 <DD>
2201 Act as if the host page size was 'pagesize' bytes
2202 </DL>
2203
2204
2205
2206 <H1><A NAME="SEC51" HREF="qemu-doc.html#TOC51">6. Compilation from the sources</A></H1>
2207
2208
2209
2210 <H2><A NAME="SEC52" HREF="qemu-doc.html#TOC52">6.1 Linux/Unix</A></H2>
2211
2212
2213
2214 <H3><A NAME="SEC53" HREF="qemu-doc.html#TOC53">6.1.1 Compilation</A></H3>
2215
2216 <P>
2217 First you must decompress the sources:
2218
2219 <PRE>
2220 cd /tmp
2221 tar zxvf qemu-x.y.z.tar.gz
2222 cd qemu-x.y.z
2223 </PRE>
2224
2225 <P>
2226 Then you configure QEMU and build it (usually no options are needed):
2227
2228 <PRE>
2229 ./configure
2230 make
2231 </PRE>
2232
2233 <P>
2234 Then type as root user:
2235
2236 <PRE>
2237 make install
2238 </PRE>
2239
2240 <P>
2241 to install QEMU in <TT>`/usr/local'</TT>.
2242
2243
2244
2245
2246 <H3><A NAME="SEC54" HREF="qemu-doc.html#TOC54">6.1.2 Tested tool versions</A></H3>
2247
2248 <P>
2249 In order to compile QEMU succesfully, it is very important that you
2250 have the right tools. The most important one is gcc. I cannot guaranty
2251 that QEMU works if you do not use a tested gcc version. Look at
2252 'configure' and 'Makefile' if you want to make a different gcc
2253 version work.
2254
2255
2256
2257 <PRE>
2258 host      gcc      binutils      glibc    linux       distribution
2259 ----------------------------------------------------------------------
2260 x86       3.2      2.13.2        2.1.3    2.4.18
2261           2.96     2.11.93.0.2   2.2.5    2.4.18      Red Hat 7.3
2262           3.2.2    2.13.90.0.18  2.3.2    2.4.20      Red Hat 9
2263
2264 PowerPC   3.3 [4]  2.13.90.0.18  2.3.1    2.4.20briq
2265           3.2
2266
2267 Alpha     3.3 [1]  2.14.90.0.4   2.2.5    2.2.20 [2]  Debian 3.0
2268
2269 Sparc32   2.95.4   2.12.90.0.1   2.2.5    2.4.18      Debian 3.0
2270
2271 ARM       2.95.4   2.12.90.0.1   2.2.5    2.4.9 [3]   Debian 3.0
2272
2273 [1] On Alpha, QEMU needs the gcc 'visibility' attribute only available
2274     for gcc version &#62;= 3.3.
2275 [2] Linux &#62;= 2.4.20 is necessary for precise exception support
2276     (untested).
2277 [3] 2.4.9-ac10-rmk2-np1-cerf2
2278
2279 [4] gcc 2.95.x generates invalid code when using too many register
2280 variables. You must use gcc 3.x on PowerPC.
2281 </PRE>
2282
2283
2284
2285 <H2><A NAME="SEC55" HREF="qemu-doc.html#TOC55">6.2 Windows</A></H2>
2286
2287
2288 <UL>
2289 <LI>Install the current versions of MSYS and MinGW from
2290
2291 <A HREF="http://www.mingw.org/">http://www.mingw.org/</A>. You can find detailed installation
2292 instructions in the download section and the FAQ.
2293
2294 <LI>Download
2295
2296 the MinGW development library of SDL 1.2.x
2297 (<TT>`SDL-devel-1.2.x-mingw32.tar.gz'</TT>) from
2298 <A HREF="http://www.libsdl.org">http://www.libsdl.org</A>. Unpack it in a temporary place, and
2299 unpack the archive <TT>`i386-mingw32msvc.tar.gz'</TT> in the MinGW tool
2300 directory. Edit the <TT>`sdl-config'</TT> script so that it gives the
2301 correct SDL directory when invoked.
2302
2303 <LI>Extract the current version of QEMU.
2304
2305
2306 <LI>Start the MSYS shell (file <TT>`msys.bat'</TT>).
2307
2308 <LI>Change to the QEMU directory. Launch <TT>`./configure'</TT> and
2309
2310 <TT>`make'</TT>.  If you have problems using SDL, verify that
2311 <TT>`sdl-config'</TT> can be launched from the MSYS command line.
2312
2313 <LI>You can install QEMU in <TT>`Program Files/Qemu'</TT> by typing
2314
2315 <TT>`make install'</TT>. Don't forget to copy <TT>`SDL.dll'</TT> in
2316 <TT>`Program Files/Qemu'</TT>.
2317
2318 </UL>
2319
2320
2321
2322 <H2><A NAME="SEC56" HREF="qemu-doc.html#TOC56">6.3 Cross compilation for Windows with Linux</A></H2>
2323
2324
2325 <UL>
2326 <LI>
2327
2328 Install the MinGW cross compilation tools available at
2329 <A HREF="http://www.mingw.org/">http://www.mingw.org/</A>.
2330
2331 <LI>
2332
2333 Install the Win32 version of SDL (<A HREF="http://www.libsdl.org">http://www.libsdl.org</A>) by
2334 unpacking <TT>`i386-mingw32msvc.tar.gz'</TT>. Set up the PATH environment
2335 variable so that <TT>`i386-mingw32msvc-sdl-config'</TT> can be launched by
2336 the QEMU configuration script.
2337
2338 <LI>
2339
2340 Configure QEMU for Windows cross compilation:
2341
2342 <PRE>
2343 ./configure --enable-mingw32
2344 </PRE>
2345
2346 If necessary, you can change the cross-prefix according to the prefix
2347 choosen for the MinGW tools with --cross-prefix. You can also use
2348 --prefix to set the Win32 install path.
2349
2350 <LI>You can install QEMU in the installation directory by typing
2351
2352 <TT>`make install'</TT>. Don't forget to copy <TT>`SDL.dll'</TT> in the
2353 installation directory.
2354
2355 </UL>
2356
2357 <P>
2358 Note: Currently, Wine does not seem able to launch
2359 QEMU for Win32.
2360
2361
2362
2363
2364 <H2><A NAME="SEC57" HREF="qemu-doc.html#TOC57">6.4 Mac OS X</A></H2>
2365
2366 <P>
2367 The Mac OS X patches are not fully merged in QEMU, so you should look
2368 at the QEMU mailing list archive to have all the necessary
2369 information.
2370
2371
2372 <P><HR><P>
2373 This document was generated on 19 December 2005 using
2374 <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.
2375 </BODY>
2376 </HTML>