]>
Commit | Line | Data |
---|---|---|
386405f7 FB |
1 | \input texinfo @c -*- texinfo -*- |
2 | ||
0806e3f6 | 3 | @iftex |
1f673135 | 4 | @settitle QEMU CPU Emulator User Documentation |
386405f7 FB |
5 | @titlepage |
6 | @sp 7 | |
1f673135 | 7 | @center @titlefont{QEMU CPU Emulator User Documentation} |
386405f7 FB |
8 | @sp 3 |
9 | @end titlepage | |
0806e3f6 | 10 | @end iftex |
386405f7 FB |
11 | |
12 | @chapter Introduction | |
13 | ||
322d0c66 | 14 | @section Features |
386405f7 | 15 | |
1f673135 FB |
16 | QEMU is a FAST! processor emulator using dynamic translation to |
17 | achieve good emulation speed. | |
1eb20527 FB |
18 | |
19 | QEMU has two operating modes: | |
0806e3f6 FB |
20 | |
21 | @itemize @minus | |
22 | ||
23 | @item | |
1f673135 | 24 | Full system emulation. In this mode, QEMU emulates a full system (for |
b671f9ed | 25 | example a PC), including a processor and various peripherals. It can |
1f673135 FB |
26 | be used to launch different Operating Systems without rebooting the |
27 | PC or to debug system code. | |
1eb20527 | 28 | |
0806e3f6 | 29 | @item |
1f673135 FB |
30 | User mode emulation (Linux host only). In this mode, QEMU can launch |
31 | Linux processes compiled for one CPU on another CPU. It can be used to | |
32 | launch the Wine Windows API emulator (@url{http://www.winehq.org}) or | |
33 | to ease cross-compilation and cross-debugging. | |
1eb20527 FB |
34 | |
35 | @end itemize | |
36 | ||
7c3fc84d | 37 | QEMU can run without an host kernel driver and yet gives acceptable |
6f2f2b24 | 38 | performance. |
322d0c66 | 39 | |
52c00a5f FB |
40 | For system emulation, the following hardware targets are supported: |
41 | @itemize | |
9d0a8e6f | 42 | @item PC (x86 or x86_64 processor) |
52c00a5f | 43 | @item PREP (PowerPC processor) |
9d0a8e6f FB |
44 | @item G3 BW PowerMac (PowerPC processor) |
45 | @item Mac99 PowerMac (PowerPC processor, in progress) | |
3475187d FB |
46 | @item Sun4m (32-bit Sparc processor) |
47 | @item Sun4u (64-bit Sparc processor, in progress) | |
9d0a8e6f | 48 | @item Malta board (32-bit MIPS processor, in progress) |
52c00a5f | 49 | @end itemize |
386405f7 | 50 | |
3475187d | 51 | For user emulation, x86, PowerPC, ARM, and Sparc32/64 CPUs are supported. |
0806e3f6 | 52 | |
5b9f457a FB |
53 | @chapter Installation |
54 | ||
15a34c63 FB |
55 | If you want to compile QEMU yourself, see @ref{compilation}. |
56 | ||
1f673135 FB |
57 | @section Linux |
58 | ||
7c3fc84d FB |
59 | If a precompiled package is available for your distribution - you just |
60 | have to install it. Otherwise, see @ref{compilation}. | |
5b9f457a | 61 | |
1f673135 | 62 | @section Windows |
8cd0ac2f | 63 | |
15a34c63 FB |
64 | Download the experimental binary installer at |
65 | @url{http://www.freeoszoo.org/download.php}. | |
d691f669 | 66 | |
1f673135 | 67 | @section Mac OS X |
d691f669 | 68 | |
15a34c63 FB |
69 | Download the experimental binary installer at |
70 | @url{http://www.freeoszoo.org/download.php}. | |
df0f11a0 | 71 | |
52c00a5f | 72 | @chapter QEMU PC System emulator invocation |
1eb20527 | 73 | |
0806e3f6 FB |
74 | @section Introduction |
75 | ||
76 | @c man begin DESCRIPTION | |
77 | ||
7c3fc84d | 78 | The QEMU System emulator simulates the |
b671f9ed | 79 | following PC peripherals: |
0806e3f6 FB |
80 | |
81 | @itemize @minus | |
15a34c63 FB |
82 | @item |
83 | i440FX host PCI bridge and PIIX3 PCI to ISA bridge | |
0806e3f6 | 84 | @item |
15a34c63 FB |
85 | Cirrus CLGD 5446 PCI VGA card or dummy VGA card with Bochs VESA |
86 | extensions (hardware level, including all non standard modes). | |
0806e3f6 FB |
87 | @item |
88 | PS/2 mouse and keyboard | |
89 | @item | |
15a34c63 | 90 | 2 PCI IDE interfaces with hard disk and CD-ROM support |
1f673135 FB |
91 | @item |
92 | Floppy disk | |
0806e3f6 | 93 | @item |
15a34c63 | 94 | NE2000 PCI network adapters |
0806e3f6 | 95 | @item |
05d5818c FB |
96 | Serial ports |
97 | @item | |
c0fe3827 FB |
98 | Creative SoundBlaster 16 sound card |
99 | @item | |
100 | ENSONIQ AudioPCI ES1370 sound card | |
101 | @item | |
102 | Adlib(OPL2) - Yamaha YM3812 compatible chip | |
0806e3f6 FB |
103 | @end itemize |
104 | ||
c0fe3827 FB |
105 | Note that adlib is only available when QEMU was configured with |
106 | -enable-adlib | |
107 | ||
15a34c63 FB |
108 | QEMU uses the PC BIOS from the Bochs project and the Plex86/Bochs LGPL |
109 | VGA BIOS. | |
110 | ||
c0fe3827 FB |
111 | QEMU uses YM3812 emulation by Tatsuyuki Satoh. |
112 | ||
0806e3f6 FB |
113 | @c man end |
114 | ||
1eb20527 FB |
115 | @section Quick Start |
116 | ||
285dc330 | 117 | Download and uncompress the linux image (@file{linux.img}) and type: |
0806e3f6 FB |
118 | |
119 | @example | |
285dc330 | 120 | qemu linux.img |
0806e3f6 FB |
121 | @end example |
122 | ||
123 | Linux should boot and give you a prompt. | |
124 | ||
6cc721cf | 125 | @node sec_invocation |
ec410fc9 FB |
126 | @section Invocation |
127 | ||
128 | @example | |
0806e3f6 FB |
129 | @c man begin SYNOPSIS |
130 | usage: qemu [options] [disk_image] | |
131 | @c man end | |
ec410fc9 FB |
132 | @end example |
133 | ||
0806e3f6 | 134 | @c man begin OPTIONS |
9d4520d0 | 135 | @var{disk_image} is a raw hard disk image for IDE hard disk 0. |
ec410fc9 FB |
136 | |
137 | General options: | |
138 | @table @option | |
2be3bc02 FB |
139 | @item -fda file |
140 | @item -fdb file | |
be3edd95 FB |
141 | Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can |
142 | use the host floppy by using @file{/dev/fd0} as filename. | |
2be3bc02 | 143 | |
ec410fc9 FB |
144 | @item -hda file |
145 | @item -hdb file | |
181f1558 FB |
146 | @item -hdc file |
147 | @item -hdd file | |
2be3bc02 | 148 | Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}). |
1f47a922 | 149 | |
181f1558 FB |
150 | @item -cdrom file |
151 | Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and | |
be3edd95 FB |
152 | @option{-cdrom} at the same time). You can use the host CD-ROM by |
153 | using @file{/dev/cdrom} as filename. | |
181f1558 | 154 | |
1f673135 FB |
155 | @item -boot [a|c|d] |
156 | Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is | |
2be3bc02 | 157 | the default. |
1f47a922 | 158 | |
181f1558 | 159 | @item -snapshot |
1f47a922 FB |
160 | Write to temporary files instead of disk image files. In this case, |
161 | the raw disk image you use is not written back. You can however force | |
162 | the write back by pressing @key{C-a s} (@xref{disk_images}). | |
ec410fc9 FB |
163 | |
164 | @item -m megs | |
15a34c63 | 165 | Set virtual RAM size to @var{megs} megabytes. Default is 128 MB. |
ec410fc9 | 166 | |
0806e3f6 FB |
167 | @item -nographic |
168 | ||
169 | Normally, QEMU uses SDL to display the VGA output. With this option, | |
170 | you can totally disable graphical output so that QEMU is a simple | |
171 | command line application. The emulated serial port is redirected on | |
172 | the console. Therefore, you can still use QEMU to debug a Linux kernel | |
173 | with a serial console. | |
174 | ||
3d11d0eb FB |
175 | @item -k language |
176 | ||
177 | Use keyboard layout @var{language} (for example @code{fr} for | |
178 | French). This option is only needed where it is not easy to get raw PC | |
179 | keycodes (e.g. on Macs or with some X11 servers). You don't need to | |
180 | use it on PC/Linux or PC/Windows hosts. | |
181 | ||
182 | The available layouts are: | |
183 | @example | |
184 | ar de-ch es fo fr-ca hu ja mk no pt-br sv | |
185 | da en-gb et fr fr-ch is lt nl pl ru th | |
186 | de en-us fi fr-be hr it lv nl-be pt sl tr | |
187 | @end example | |
188 | ||
189 | The default is @code{en-us}. | |
190 | ||
a8c490cd FB |
191 | @item -enable-audio |
192 | ||
1d14ffa9 FB |
193 | Will enable audio and all the sound hardware QEMU was built with. |
194 | ||
195 | @item -audio-help | |
196 | ||
197 | Will show the audio subsystem help: list of drivers, tunable | |
198 | parameters. | |
199 | ||
200 | @item -soundhw card1,card2,... | |
201 | ||
202 | Enable audio and selected sound hardware. Use ? to print all | |
203 | available sound hardware. | |
204 | ||
205 | @example | |
206 | qemu -soundhw sb16,adlib hda | |
207 | qemu -soundhw es1370 hda | |
208 | qemu -soundhw ? | |
209 | @end example | |
a8c490cd | 210 | |
15a34c63 FB |
211 | @item -localtime |
212 | Set the real time clock to local time (the default is to UTC | |
213 | time). This option is needed to have correct date in MS-DOS or | |
214 | Windows. | |
215 | ||
d63d307f FB |
216 | @item -full-screen |
217 | Start in full screen. | |
218 | ||
f7cce898 FB |
219 | @item -pidfile file |
220 | Store the QEMU process PID in @var{file}. It is useful if you launch QEMU | |
221 | from a script. | |
222 | ||
9d0a8e6f FB |
223 | @item -win2k-hack |
224 | Use it when installing Windows 2000 to avoid a disk full bug. After | |
225 | Windows 2000 is installed, you no longer need this option (this option | |
226 | slows down the IDE transfers). | |
227 | ||
0806e3f6 FB |
228 | @end table |
229 | ||
1f673135 FB |
230 | Network options: |
231 | ||
232 | @table @option | |
233 | ||
234 | @item -n script | |
52c00a5f FB |
235 | Set TUN/TAP network init script [default=/etc/qemu-ifup]. This script |
236 | is launched to configure the host network interface (usually tun0) | |
1f673135 FB |
237 | corresponding to the virtual NE2000 card. |
238 | ||
3f1a88f4 FB |
239 | @item -nics n |
240 | ||
241 | Simulate @var{n} network cards (the default is 1). | |
242 | ||
1f673135 FB |
243 | @item -macaddr addr |
244 | ||
245 | Set the mac address of the first interface (the format is | |
246 | aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each | |
247 | new network interface. | |
248 | ||
52c00a5f FB |
249 | @item -tun-fd fd |
250 | Assumes @var{fd} talks to a tap/tun host network interface and use | |
251 | it. Read @url{http://bellard.org/qemu/tetrinet.html} to have an | |
252 | example of its use. | |
253 | ||
254 | @item -user-net | |
15a34c63 FB |
255 | Use the user mode network stack. This is the default if no tun/tap |
256 | network init script is found. | |
52c00a5f | 257 | |
9bf05444 FB |
258 | @item -tftp prefix |
259 | When using the user mode network stack, activate a built-in TFTP | |
260 | server. All filenames beginning with @var{prefix} can be downloaded | |
261 | from the host to the guest using a TFTP client. The TFTP client on the | |
262 | guest must be configured in binary mode (use the command @code{bin} of | |
263 | the Unix TFTP client). The host IP address on the guest is as usual | |
264 | 10.0.2.2. | |
265 | ||
2518bd0d FB |
266 | @item -smb dir |
267 | When using the user mode network stack, activate a built-in SMB | |
268 | server so that Windows OSes can access to the host files in @file{dir} | |
269 | transparently. | |
270 | ||
271 | In the guest Windows OS, the line: | |
272 | @example | |
273 | 10.0.2.4 smbserver | |
274 | @end example | |
275 | must be added in the file @file{C:\WINDOWS\LMHOSTS} (for windows 9x/Me) | |
276 | or @file{C:\WINNT\SYSTEM32\DRIVERS\ETC\LMHOSTS} (Windows NT/2000). | |
277 | ||
278 | Then @file{dir} can be accessed in @file{\\smbserver\qemu}. | |
279 | ||
280 | Note that a SAMBA server must be installed on the host OS in | |
281 | @file{/usr/sbin/smbd}. QEMU was tested succesfully with smbd version | |
6cc721cf | 282 | 2.2.7a from the Red Hat 9 and version 3.0.10-1.fc3 from Fedora Core 3. |
2518bd0d | 283 | |
9bf05444 FB |
284 | @item -redir [tcp|udp]:host-port:[guest-host]:guest-port |
285 | ||
286 | When using the user mode network stack, redirect incoming TCP or UDP | |
287 | connections to the host port @var{host-port} to the guest | |
288 | @var{guest-host} on guest port @var{guest-port}. If @var{guest-host} | |
289 | is not specified, its value is 10.0.2.15 (default address given by the | |
290 | built-in DHCP server). | |
291 | ||
292 | For example, to redirect host X11 connection from screen 1 to guest | |
293 | screen 0, use the following: | |
294 | ||
295 | @example | |
296 | # on the host | |
297 | qemu -redir tcp:6001::6000 [...] | |
298 | # this host xterm should open in the guest X11 server | |
299 | xterm -display :1 | |
300 | @end example | |
301 | ||
302 | To redirect telnet connections from host port 5555 to telnet port on | |
303 | the guest, use the following: | |
304 | ||
305 | @example | |
306 | # on the host | |
307 | qemu -redir tcp:5555::23 [...] | |
308 | telnet localhost 5555 | |
309 | @end example | |
310 | ||
311 | Then when you use on the host @code{telnet localhost 5555}, you | |
312 | connect to the guest telnet server. | |
313 | ||
52c00a5f | 314 | @item -dummy-net |
15a34c63 | 315 | Use the dummy network stack: no packet will be received by the network |
52c00a5f | 316 | cards. |
1f673135 FB |
317 | |
318 | @end table | |
319 | ||
320 | Linux boot specific. When using this options, you can use a given | |
321 | Linux kernel without installing it in the disk image. It can be useful | |
322 | for easier testing of various kernels. | |
323 | ||
0806e3f6 FB |
324 | @table @option |
325 | ||
326 | @item -kernel bzImage | |
327 | Use @var{bzImage} as kernel image. | |
328 | ||
329 | @item -append cmdline | |
330 | Use @var{cmdline} as kernel command line | |
331 | ||
332 | @item -initrd file | |
333 | Use @var{file} as initial ram disk. | |
334 | ||
ec410fc9 FB |
335 | @end table |
336 | ||
15a34c63 | 337 | Debug/Expert options: |
ec410fc9 | 338 | @table @option |
a0a821a4 FB |
339 | |
340 | @item -serial dev | |
341 | Redirect the virtual serial port to host device @var{dev}. Available | |
342 | devices are: | |
343 | @table @code | |
344 | @item vc | |
345 | Virtual console | |
346 | @item pty | |
347 | [Linux only] Pseudo TTY (a new PTY is automatically allocated) | |
348 | @item null | |
349 | void device | |
350 | @item stdio | |
351 | [Unix only] standard input/output | |
352 | @end table | |
353 | The default device is @code{vc} in graphical mode and @code{stdio} in | |
354 | non graphical mode. | |
355 | ||
05d5818c FB |
356 | This option can be used several times to simulate up to 4 serials |
357 | ports. | |
358 | ||
a0a821a4 FB |
359 | @item -monitor dev |
360 | Redirect the monitor to host device @var{dev} (same devices as the | |
361 | serial port). | |
362 | The default device is @code{vc} in graphical mode and @code{stdio} in | |
363 | non graphical mode. | |
364 | ||
ec410fc9 | 365 | @item -s |
0806e3f6 | 366 | Wait gdb connection to port 1234 (@xref{gdb_usage}). |
ec410fc9 FB |
367 | @item -p port |
368 | Change gdb connection port. | |
52c00a5f FB |
369 | @item -S |
370 | Do not start CPU at startup (you must type 'c' in the monitor). | |
ec410fc9 | 371 | @item -d |
9d4520d0 | 372 | Output log in /tmp/qemu.log |
46d4767d FB |
373 | @item -hdachs c,h,s,[,t] |
374 | Force hard disk 0 physical geometry (1 <= @var{c} <= 16383, 1 <= | |
375 | @var{h} <= 16, 1 <= @var{s} <= 63) and optionally force the BIOS | |
376 | translation mode (@var{t}=none, lba or auto). Usually QEMU can guess | |
377 | all thoses parameters. This option is useful for old MS-DOS disk | |
378 | images. | |
7c3fc84d | 379 | |
15a34c63 FB |
380 | @item -isa |
381 | Simulate an ISA-only system (default is PCI system). | |
382 | @item -std-vga | |
383 | Simulate a standard VGA card with Bochs VBE extensions (default is | |
384 | Cirrus Logic GD5446 PCI VGA) | |
d63d307f FB |
385 | @item -loadvm file |
386 | Start right away with a saved state (@code{loadvm} in monitor) | |
ec410fc9 FB |
387 | @end table |
388 | ||
3e11db9a FB |
389 | @c man end |
390 | ||
391 | @section Keys | |
392 | ||
393 | @c man begin OPTIONS | |
394 | ||
a1b74fe8 FB |
395 | During the graphical emulation, you can use the following keys: |
396 | @table @key | |
f9859310 | 397 | @item Ctrl-Alt-f |
a1b74fe8 | 398 | Toggle full screen |
a0a821a4 | 399 | |
f9859310 | 400 | @item Ctrl-Alt-n |
a0a821a4 FB |
401 | Switch to virtual console 'n'. Standard console mappings are: |
402 | @table @emph | |
403 | @item 1 | |
404 | Target system display | |
405 | @item 2 | |
406 | Monitor | |
407 | @item 3 | |
408 | Serial port | |
a1b74fe8 FB |
409 | @end table |
410 | ||
f9859310 | 411 | @item Ctrl-Alt |
a0a821a4 FB |
412 | Toggle mouse and keyboard grab. |
413 | @end table | |
414 | ||
3e11db9a FB |
415 | In the virtual consoles, you can use @key{Ctrl-Up}, @key{Ctrl-Down}, |
416 | @key{Ctrl-PageUp} and @key{Ctrl-PageDown} to move in the back log. | |
417 | ||
a0a821a4 FB |
418 | During emulation, if you are using the @option{-nographic} option, use |
419 | @key{Ctrl-a h} to get terminal commands: | |
ec410fc9 FB |
420 | |
421 | @table @key | |
a1b74fe8 | 422 | @item Ctrl-a h |
ec410fc9 | 423 | Print this help |
a1b74fe8 | 424 | @item Ctrl-a x |
ec410fc9 | 425 | Exit emulatior |
a1b74fe8 | 426 | @item Ctrl-a s |
1f47a922 | 427 | Save disk data back to file (if -snapshot) |
a1b74fe8 | 428 | @item Ctrl-a b |
1f673135 | 429 | Send break (magic sysrq in Linux) |
a1b74fe8 | 430 | @item Ctrl-a c |
1f673135 | 431 | Switch between console and monitor |
a1b74fe8 FB |
432 | @item Ctrl-a Ctrl-a |
433 | Send Ctrl-a | |
ec410fc9 | 434 | @end table |
0806e3f6 FB |
435 | @c man end |
436 | ||
437 | @ignore | |
438 | ||
439 | @setfilename qemu | |
440 | @settitle QEMU System Emulator | |
441 | ||
1f673135 FB |
442 | @c man begin SEEALSO |
443 | The HTML documentation of QEMU for more precise information and Linux | |
444 | user mode emulator invocation. | |
445 | @c man end | |
446 | ||
447 | @c man begin AUTHOR | |
448 | Fabrice Bellard | |
449 | @c man end | |
450 | ||
451 | @end ignore | |
452 | ||
453 | @end ignore | |
454 | ||
1f673135 FB |
455 | @section QEMU Monitor |
456 | ||
457 | The QEMU monitor is used to give complex commands to the QEMU | |
458 | emulator. You can use it to: | |
459 | ||
460 | @itemize @minus | |
461 | ||
462 | @item | |
463 | Remove or insert removable medias images | |
464 | (such as CD-ROM or floppies) | |
465 | ||
466 | @item | |
467 | Freeze/unfreeze the Virtual Machine (VM) and save or restore its state | |
468 | from a disk file. | |
469 | ||
470 | @item Inspect the VM state without an external debugger. | |
471 | ||
472 | @end itemize | |
473 | ||
474 | @subsection Commands | |
475 | ||
476 | The following commands are available: | |
477 | ||
478 | @table @option | |
479 | ||
480 | @item help or ? [cmd] | |
481 | Show the help for all commands or just for command @var{cmd}. | |
482 | ||
483 | @item commit | |
484 | Commit changes to the disk images (if -snapshot is used) | |
485 | ||
486 | @item info subcommand | |
487 | show various information about the system state | |
488 | ||
489 | @table @option | |
490 | @item info network | |
491 | show the network state | |
492 | @item info block | |
493 | show the block devices | |
494 | @item info registers | |
495 | show the cpu registers | |
496 | @item info history | |
497 | show the command line history | |
498 | @end table | |
499 | ||
500 | @item q or quit | |
501 | Quit the emulator. | |
502 | ||
503 | @item eject [-f] device | |
504 | Eject a removable media (use -f to force it). | |
505 | ||
506 | @item change device filename | |
507 | Change a removable media. | |
508 | ||
509 | @item screendump filename | |
510 | Save screen into PPM image @var{filename}. | |
511 | ||
512 | @item log item1[,...] | |
513 | Activate logging of the specified items to @file{/tmp/qemu.log}. | |
514 | ||
515 | @item savevm filename | |
516 | Save the whole virtual machine state to @var{filename}. | |
517 | ||
518 | @item loadvm filename | |
519 | Restore the whole virtual machine state from @var{filename}. | |
520 | ||
521 | @item stop | |
522 | Stop emulation. | |
523 | ||
524 | @item c or cont | |
525 | Resume emulation. | |
526 | ||
527 | @item gdbserver [port] | |
528 | Start gdbserver session (default port=1234) | |
529 | ||
530 | @item x/fmt addr | |
531 | Virtual memory dump starting at @var{addr}. | |
532 | ||
533 | @item xp /fmt addr | |
534 | Physical memory dump starting at @var{addr}. | |
535 | ||
536 | @var{fmt} is a format which tells the command how to format the | |
537 | data. Its syntax is: @option{/@{count@}@{format@}@{size@}} | |
538 | ||
539 | @table @var | |
540 | @item count | |
541 | is the number of items to be dumped. | |
542 | ||
543 | @item format | |
544 | can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal), | |
545 | c (char) or i (asm instruction). | |
546 | ||
547 | @item size | |
52c00a5f FB |
548 | can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, |
549 | @code{h} or @code{w} can be specified with the @code{i} format to | |
550 | respectively select 16 or 32 bit code instruction size. | |
1f673135 FB |
551 | |
552 | @end table | |
553 | ||
554 | Examples: | |
555 | @itemize | |
556 | @item | |
557 | Dump 10 instructions at the current instruction pointer: | |
558 | @example | |
559 | (qemu) x/10i $eip | |
560 | 0x90107063: ret | |
561 | 0x90107064: sti | |
562 | 0x90107065: lea 0x0(%esi,1),%esi | |
563 | 0x90107069: lea 0x0(%edi,1),%edi | |
564 | 0x90107070: ret | |
565 | 0x90107071: jmp 0x90107080 | |
566 | 0x90107073: nop | |
567 | 0x90107074: nop | |
568 | 0x90107075: nop | |
569 | 0x90107076: nop | |
570 | @end example | |
571 | ||
572 | @item | |
573 | Dump 80 16 bit values at the start of the video memory. | |
574 | @example | |
575 | (qemu) xp/80hx 0xb8000 | |
576 | 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42 | |
577 | 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41 | |
578 | 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72 | |
579 | 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73 | |
580 | 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20 | |
581 | 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720 | |
582 | 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
583 | 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
584 | 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
585 | 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
586 | @end example | |
587 | @end itemize | |
588 | ||
589 | @item p or print/fmt expr | |
590 | ||
591 | Print expression value. Only the @var{format} part of @var{fmt} is | |
592 | used. | |
0806e3f6 | 593 | |
a3a91a35 FB |
594 | @item sendkey keys |
595 | ||
596 | Send @var{keys} to the emulator. Use @code{-} to press several keys | |
597 | simultaneously. Example: | |
598 | @example | |
599 | sendkey ctrl-alt-f1 | |
600 | @end example | |
601 | ||
602 | This command is useful to send keys that your graphical user interface | |
603 | intercepts at low level, such as @code{ctrl-alt-f1} in X Window. | |
604 | ||
15a34c63 FB |
605 | @item system_reset |
606 | ||
607 | Reset the system. | |
608 | ||
1f673135 | 609 | @end table |
0806e3f6 | 610 | |
1f673135 FB |
611 | @subsection Integer expressions |
612 | ||
613 | The monitor understands integers expressions for every integer | |
614 | argument. You can use register names to get the value of specifics | |
615 | CPU registers by prefixing them with @emph{$}. | |
ec410fc9 | 616 | |
1f47a922 FB |
617 | @node disk_images |
618 | @section Disk Images | |
619 | ||
acd935ef FB |
620 | Since version 0.6.1, QEMU supports many disk image formats, including |
621 | growable disk images (their size increase as non empty sectors are | |
622 | written), compressed and encrypted disk images. | |
1f47a922 | 623 | |
acd935ef FB |
624 | @subsection Quick start for disk image creation |
625 | ||
626 | You can create a disk image with the command: | |
1f47a922 | 627 | @example |
acd935ef | 628 | qemu-img create myimage.img mysize |
1f47a922 | 629 | @end example |
acd935ef FB |
630 | where @var{myimage.img} is the disk image filename and @var{mysize} is its |
631 | size in kilobytes. You can add an @code{M} suffix to give the size in | |
632 | megabytes and a @code{G} suffix for gigabytes. | |
633 | ||
634 | @xref{qemu_img_invocation} for more information. | |
1f47a922 FB |
635 | |
636 | @subsection Snapshot mode | |
637 | ||
638 | If you use the option @option{-snapshot}, all disk images are | |
639 | considered as read only. When sectors in written, they are written in | |
640 | a temporary file created in @file{/tmp}. You can however force the | |
acd935ef FB |
641 | write back to the raw disk images by using the @code{commit} monitor |
642 | command (or @key{C-a s} in the serial console). | |
1f47a922 | 643 | |
acd935ef FB |
644 | @node qemu_img_invocation |
645 | @subsection @code{qemu-img} Invocation | |
1f47a922 | 646 | |
acd935ef | 647 | @include qemu-img.texi |
05efe46e | 648 | |
9d4fb82e FB |
649 | @section Network emulation |
650 | ||
651 | QEMU simulates up to 6 networks cards (NE2000 boards). Each card can | |
652 | be connected to a specific host network interface. | |
653 | ||
654 | @subsection Using tun/tap network interface | |
655 | ||
656 | This is the standard way to emulate network. QEMU adds a virtual | |
657 | network device on your host (called @code{tun0}), and you can then | |
658 | configure it as if it was a real ethernet card. | |
659 | ||
660 | As an example, you can download the @file{linux-test-xxx.tar.gz} | |
661 | archive and copy the script @file{qemu-ifup} in @file{/etc} and | |
662 | configure properly @code{sudo} so that the command @code{ifconfig} | |
663 | contained in @file{qemu-ifup} can be executed as root. You must verify | |
664 | that your host kernel supports the TUN/TAP network interfaces: the | |
665 | device @file{/dev/net/tun} must be present. | |
666 | ||
667 | See @ref{direct_linux_boot} to have an example of network use with a | |
668 | Linux distribution. | |
669 | ||
670 | @subsection Using the user mode network stack | |
671 | ||
443f1376 FB |
672 | By using the option @option{-user-net} or if you have no tun/tap init |
673 | script, QEMU uses a completely user mode network stack (you don't need | |
674 | root priviledge to use the virtual network). The virtual network | |
675 | configuration is the following: | |
9d4fb82e FB |
676 | |
677 | @example | |
678 | ||
679 | QEMU Virtual Machine <------> Firewall/DHCP server <-----> Internet | |
680 | (10.0.2.x) | (10.0.2.2) | |
681 | | | |
2518bd0d FB |
682 | ----> DNS server (10.0.2.3) |
683 | | | |
684 | ----> SMB server (10.0.2.4) | |
9d4fb82e FB |
685 | @end example |
686 | ||
687 | The QEMU VM behaves as if it was behind a firewall which blocks all | |
688 | incoming connections. You can use a DHCP client to automatically | |
689 | configure the network in the QEMU VM. | |
690 | ||
691 | In order to check that the user mode network is working, you can ping | |
692 | the address 10.0.2.2 and verify that you got an address in the range | |
693 | 10.0.2.x from the QEMU virtual DHCP server. | |
694 | ||
b415a407 FB |
695 | Note that @code{ping} is not supported reliably to the internet as it |
696 | would require root priviledges. It means you can only ping the local | |
697 | router (10.0.2.2). | |
698 | ||
9bf05444 FB |
699 | When using the built-in TFTP server, the router is also the TFTP |
700 | server. | |
701 | ||
702 | When using the @option{-redir} option, TCP or UDP connections can be | |
703 | redirected from the host to the guest. It allows for example to | |
704 | redirect X11, telnet or SSH connections. | |
443f1376 | 705 | |
9d4fb82e FB |
706 | @node direct_linux_boot |
707 | @section Direct Linux Boot | |
1f673135 FB |
708 | |
709 | This section explains how to launch a Linux kernel inside QEMU without | |
710 | having to make a full bootable image. It is very useful for fast Linux | |
711 | kernel testing. The QEMU network configuration is also explained. | |
712 | ||
713 | @enumerate | |
714 | @item | |
715 | Download the archive @file{linux-test-xxx.tar.gz} containing a Linux | |
716 | kernel and a disk image. | |
717 | ||
718 | @item Optional: If you want network support (for example to launch X11 examples), you | |
719 | must copy the script @file{qemu-ifup} in @file{/etc} and configure | |
720 | properly @code{sudo} so that the command @code{ifconfig} contained in | |
721 | @file{qemu-ifup} can be executed as root. You must verify that your host | |
722 | kernel supports the TUN/TAP network interfaces: the device | |
723 | @file{/dev/net/tun} must be present. | |
724 | ||
725 | When network is enabled, there is a virtual network connection between | |
726 | the host kernel and the emulated kernel. The emulated kernel is seen | |
727 | from the host kernel at IP address 172.20.0.2 and the host kernel is | |
728 | seen from the emulated kernel at IP address 172.20.0.1. | |
729 | ||
730 | @item Launch @code{qemu.sh}. You should have the following output: | |
731 | ||
732 | @example | |
733 | > ./qemu.sh | |
734 | Connected to host network interface: tun0 | |
735 | 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 | |
736 | BIOS-provided physical RAM map: | |
737 | BIOS-e801: 0000000000000000 - 000000000009f000 (usable) | |
738 | BIOS-e801: 0000000000100000 - 0000000002000000 (usable) | |
739 | 32MB LOWMEM available. | |
740 | On node 0 totalpages: 8192 | |
741 | zone(0): 4096 pages. | |
742 | zone(1): 4096 pages. | |
743 | zone(2): 0 pages. | |
744 | Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0 | |
745 | ide_setup: ide2=noprobe | |
746 | ide_setup: ide3=noprobe | |
747 | ide_setup: ide4=noprobe | |
748 | ide_setup: ide5=noprobe | |
749 | Initializing CPU#0 | |
750 | Detected 2399.621 MHz processor. | |
751 | Console: colour EGA 80x25 | |
752 | Calibrating delay loop... 4744.80 BogoMIPS | |
753 | Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem) | |
754 | Dentry cache hash table entries: 4096 (order: 3, 32768 bytes) | |
755 | Inode cache hash table entries: 2048 (order: 2, 16384 bytes) | |
756 | Mount cache hash table entries: 512 (order: 0, 4096 bytes) | |
757 | Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) | |
758 | Page-cache hash table entries: 8192 (order: 3, 32768 bytes) | |
759 | CPU: Intel Pentium Pro stepping 03 | |
760 | Checking 'hlt' instruction... OK. | |
761 | POSIX conformance testing by UNIFIX | |
762 | Linux NET4.0 for Linux 2.4 | |
763 | Based upon Swansea University Computer Society NET3.039 | |
764 | Initializing RT netlink socket | |
765 | apm: BIOS not found. | |
766 | Starting kswapd | |
767 | Journalled Block Device driver loaded | |
768 | Detected PS/2 Mouse Port. | |
769 | pty: 256 Unix98 ptys configured | |
770 | Serial driver version 5.05c (2001-07-08) with no serial options enabled | |
771 | ttyS00 at 0x03f8 (irq = 4) is a 16450 | |
772 | ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com) | |
773 | Last modified Nov 1, 2000 by Paul Gortmaker | |
774 | NE*000 ethercard probe at 0x300: 52 54 00 12 34 56 | |
775 | eth0: NE2000 found at 0x300, using IRQ 9. | |
776 | RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize | |
777 | Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4 | |
778 | ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx | |
779 | hda: QEMU HARDDISK, ATA DISK drive | |
780 | ide0 at 0x1f0-0x1f7,0x3f6 on irq 14 | |
781 | hda: attached ide-disk driver. | |
782 | hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63 | |
783 | Partition check: | |
784 | hda: | |
785 | Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996 | |
786 | NET4: Linux TCP/IP 1.0 for NET4.0 | |
787 | IP Protocols: ICMP, UDP, TCP, IGMP | |
788 | IP: routing cache hash table of 512 buckets, 4Kbytes | |
789 | TCP: Hash tables configured (established 2048 bind 4096) | |
790 | NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. | |
791 | EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended | |
792 | VFS: Mounted root (ext2 filesystem). | |
793 | Freeing unused kernel memory: 64k freed | |
794 | ||
795 | 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 | |
796 | ||
797 | QEMU Linux test distribution (based on Redhat 9) | |
798 | ||
799 | Type 'exit' to halt the system | |
800 | ||
801 | sh-2.05b# | |
802 | @end example | |
803 | ||
804 | @item | |
805 | Then you can play with the kernel inside the virtual serial console. You | |
806 | can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help | |
807 | about the keys you can type inside the virtual serial console. In | |
808 | particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as | |
809 | the Magic SysRq key. | |
810 | ||
811 | @item | |
812 | If the network is enabled, launch the script @file{/etc/linuxrc} in the | |
813 | emulator (don't forget the leading dot): | |
814 | @example | |
815 | . /etc/linuxrc | |
816 | @end example | |
817 | ||
818 | Then enable X11 connections on your PC from the emulated Linux: | |
819 | @example | |
820 | xhost +172.20.0.2 | |
821 | @end example | |
822 | ||
823 | You can now launch @file{xterm} or @file{xlogo} and verify that you have | |
824 | a real Virtual Linux system ! | |
825 | ||
826 | @end enumerate | |
827 | ||
828 | NOTES: | |
829 | @enumerate | |
830 | @item | |
831 | A 2.5.74 kernel is also included in the archive. Just | |
832 | replace the bzImage in qemu.sh to try it. | |
833 | ||
1f673135 FB |
834 | @item |
835 | In order to exit cleanly from qemu, you can do a @emph{shutdown} inside | |
836 | qemu. qemu will automatically exit when the Linux shutdown is done. | |
837 | ||
838 | @item | |
839 | You can boot slightly faster by disabling the probe of non present IDE | |
840 | interfaces. To do so, add the following options on the kernel command | |
841 | line: | |
842 | @example | |
843 | ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe | |
844 | @end example | |
845 | ||
846 | @item | |
847 | The example disk image is a modified version of the one made by Kevin | |
848 | Lawton for the plex86 Project (@url{www.plex86.org}). | |
849 | ||
850 | @end enumerate | |
851 | ||
0806e3f6 | 852 | @node gdb_usage |
da415d54 FB |
853 | @section GDB usage |
854 | ||
855 | QEMU has a primitive support to work with gdb, so that you can do | |
0806e3f6 | 856 | 'Ctrl-C' while the virtual machine is running and inspect its state. |
da415d54 | 857 | |
9d4520d0 | 858 | In order to use gdb, launch qemu with the '-s' option. It will wait for a |
da415d54 FB |
859 | gdb connection: |
860 | @example | |
6c9bf893 | 861 | > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda" |
da415d54 FB |
862 | Connected to host network interface: tun0 |
863 | Waiting gdb connection on port 1234 | |
864 | @end example | |
865 | ||
866 | Then launch gdb on the 'vmlinux' executable: | |
867 | @example | |
868 | > gdb vmlinux | |
869 | @end example | |
870 | ||
871 | In gdb, connect to QEMU: | |
872 | @example | |
6c9bf893 | 873 | (gdb) target remote localhost:1234 |
da415d54 FB |
874 | @end example |
875 | ||
876 | Then you can use gdb normally. For example, type 'c' to launch the kernel: | |
877 | @example | |
878 | (gdb) c | |
879 | @end example | |
880 | ||
0806e3f6 FB |
881 | Here are some useful tips in order to use gdb on system code: |
882 | ||
883 | @enumerate | |
884 | @item | |
885 | Use @code{info reg} to display all the CPU registers. | |
886 | @item | |
887 | Use @code{x/10i $eip} to display the code at the PC position. | |
888 | @item | |
889 | Use @code{set architecture i8086} to dump 16 bit code. Then use | |
890 | @code{x/10i $cs*16+*eip} to dump the code at the PC position. | |
891 | @end enumerate | |
892 | ||
1a084f3d FB |
893 | @section Target OS specific information |
894 | ||
895 | @subsection Linux | |
896 | ||
15a34c63 FB |
897 | To have access to SVGA graphic modes under X11, use the @code{vesa} or |
898 | the @code{cirrus} X11 driver. For optimal performances, use 16 bit | |
899 | color depth in the guest and the host OS. | |
1a084f3d | 900 | |
e3371e62 FB |
901 | When using a 2.6 guest Linux kernel, you should add the option |
902 | @code{clock=pit} on the kernel command line because the 2.6 Linux | |
903 | kernels make very strict real time clock checks by default that QEMU | |
904 | cannot simulate exactly. | |
905 | ||
7c3fc84d FB |
906 | When using a 2.6 guest Linux kernel, verify that the 4G/4G patch is |
907 | not activated because QEMU is slower with this patch. The QEMU | |
908 | Accelerator Module is also much slower in this case. Earlier Fedora | |
909 | Core 3 Linux kernel (< 2.6.9-1.724_FC3) were known to incorporte this | |
910 | patch by default. Newer kernels don't have it. | |
911 | ||
1a084f3d FB |
912 | @subsection Windows |
913 | ||
914 | If you have a slow host, using Windows 95 is better as it gives the | |
915 | best speed. Windows 2000 is also a good choice. | |
916 | ||
e3371e62 FB |
917 | @subsubsection SVGA graphic modes support |
918 | ||
919 | QEMU emulates a Cirrus Logic GD5446 Video | |
15a34c63 FB |
920 | card. All Windows versions starting from Windows 95 should recognize |
921 | and use this graphic card. For optimal performances, use 16 bit color | |
922 | depth in the guest and the host OS. | |
1a084f3d | 923 | |
e3371e62 FB |
924 | @subsubsection CPU usage reduction |
925 | ||
926 | Windows 9x does not correctly use the CPU HLT | |
15a34c63 FB |
927 | instruction. The result is that it takes host CPU cycles even when |
928 | idle. You can install the utility from | |
929 | @url{http://www.user.cityline.ru/~maxamn/amnhltm.zip} to solve this | |
930 | problem. Note that no such tool is needed for NT, 2000 or XP. | |
1a084f3d | 931 | |
9d0a8e6f | 932 | @subsubsection Windows 2000 disk full problem |
e3371e62 | 933 | |
9d0a8e6f FB |
934 | Windows 2000 has a bug which gives a disk full problem during its |
935 | installation. When installing it, use the @option{-win2k-hack} QEMU | |
936 | option to enable a specific workaround. After Windows 2000 is | |
937 | installed, you no longer need this option (this option slows down the | |
938 | IDE transfers). | |
e3371e62 | 939 | |
6cc721cf FB |
940 | @subsubsection Windows 2000 shutdown |
941 | ||
942 | Windows 2000 cannot automatically shutdown in QEMU although Windows 98 | |
943 | can. It comes from the fact that Windows 2000 does not automatically | |
944 | use the APM driver provided by the BIOS. | |
945 | ||
946 | In order to correct that, do the following (thanks to Struan | |
947 | Bartlett): go to the Control Panel => Add/Remove Hardware & Next => | |
948 | Add/Troubleshoot a device => Add a new device & Next => No, select the | |
949 | hardware from a list & Next => NT Apm/Legacy Support & Next => Next | |
950 | (again) a few times. Now the driver is installed and Windows 2000 now | |
951 | correctly instructs QEMU to shutdown at the appropriate moment. | |
952 | ||
953 | @subsubsection Share a directory between Unix and Windows | |
954 | ||
955 | See @ref{sec_invocation} about the help of the option @option{-smb}. | |
956 | ||
e3371e62 FB |
957 | @subsubsection Windows XP security problems |
958 | ||
959 | Some releases of Windows XP install correctly but give a security | |
960 | error when booting: | |
961 | @example | |
962 | A problem is preventing Windows from accurately checking the | |
963 | license for this computer. Error code: 0x800703e6. | |
964 | @end example | |
965 | The only known workaround is to boot in Safe mode | |
966 | without networking support. | |
967 | ||
968 | Future QEMU releases are likely to correct this bug. | |
969 | ||
a0a821a4 FB |
970 | @subsection MS-DOS and FreeDOS |
971 | ||
972 | @subsubsection CPU usage reduction | |
973 | ||
974 | DOS does not correctly use the CPU HLT instruction. The result is that | |
975 | it takes host CPU cycles even when idle. You can install the utility | |
976 | from @url{http://www.vmware.com/software/dosidle210.zip} to solve this | |
977 | problem. | |
978 | ||
15a34c63 | 979 | @chapter QEMU PowerPC System emulator invocation |
1a084f3d | 980 | |
15a34c63 FB |
981 | Use the executable @file{qemu-system-ppc} to simulate a complete PREP |
982 | or PowerMac PowerPC system. | |
1a084f3d | 983 | |
b671f9ed | 984 | QEMU emulates the following PowerMac peripherals: |
1a084f3d | 985 | |
15a34c63 FB |
986 | @itemize @minus |
987 | @item | |
988 | UniNorth PCI Bridge | |
989 | @item | |
990 | PCI VGA compatible card with VESA Bochs Extensions | |
991 | @item | |
992 | 2 PMAC IDE interfaces with hard disk and CD-ROM support | |
993 | @item | |
994 | NE2000 PCI adapters | |
995 | @item | |
996 | Non Volatile RAM | |
997 | @item | |
998 | VIA-CUDA with ADB keyboard and mouse. | |
1a084f3d FB |
999 | @end itemize |
1000 | ||
b671f9ed | 1001 | QEMU emulates the following PREP peripherals: |
52c00a5f FB |
1002 | |
1003 | @itemize @minus | |
1004 | @item | |
15a34c63 FB |
1005 | PCI Bridge |
1006 | @item | |
1007 | PCI VGA compatible card with VESA Bochs Extensions | |
1008 | @item | |
52c00a5f FB |
1009 | 2 IDE interfaces with hard disk and CD-ROM support |
1010 | @item | |
1011 | Floppy disk | |
1012 | @item | |
15a34c63 | 1013 | NE2000 network adapters |
52c00a5f FB |
1014 | @item |
1015 | Serial port | |
1016 | @item | |
1017 | PREP Non Volatile RAM | |
15a34c63 FB |
1018 | @item |
1019 | PC compatible keyboard and mouse. | |
52c00a5f FB |
1020 | @end itemize |
1021 | ||
15a34c63 FB |
1022 | QEMU uses the Open Hack'Ware Open Firmware Compatible BIOS available at |
1023 | @url{http://site.voila.fr/jmayer/OpenHackWare/index.htm}. | |
1024 | ||
52c00a5f FB |
1025 | You can read the qemu PC system emulation chapter to have more |
1026 | informations about QEMU usage. | |
1027 | ||
15a34c63 FB |
1028 | @c man begin OPTIONS |
1029 | ||
1030 | The following options are specific to the PowerPC emulation: | |
1031 | ||
1032 | @table @option | |
1033 | ||
1034 | @item -prep | |
1035 | Simulate a PREP system (default is PowerMAC) | |
1036 | ||
1037 | @item -g WxH[xDEPTH] | |
1038 | ||
1039 | Set the initial VGA graphic mode. The default is 800x600x15. | |
1040 | ||
1041 | @end table | |
1042 | ||
1043 | @c man end | |
1044 | ||
1045 | ||
52c00a5f FB |
1046 | More information is available at |
1047 | @url{http://jocelyn.mayer.free.fr/qemu-ppc/}. | |
1048 | ||
3475187d | 1049 | @chapter Sparc32 System emulator invocation |
e80cfcfc FB |
1050 | |
1051 | Use the executable @file{qemu-system-sparc} to simulate a JavaStation | |
3475187d | 1052 | (sun4m architecture). The emulation is somewhat complete. |
e80cfcfc | 1053 | |
b671f9ed | 1054 | QEMU emulates the following sun4m peripherals: |
e80cfcfc FB |
1055 | |
1056 | @itemize @minus | |
3475187d | 1057 | @item |
e80cfcfc FB |
1058 | IOMMU |
1059 | @item | |
1060 | TCX Frame buffer | |
1061 | @item | |
1062 | Lance (Am7990) Ethernet | |
1063 | @item | |
1064 | Non Volatile RAM M48T08 | |
1065 | @item | |
3475187d FB |
1066 | Slave I/O: timers, interrupt controllers, Zilog serial ports, keyboard |
1067 | and power/reset logic | |
1068 | @item | |
1069 | ESP SCSI controller with hard disk and CD-ROM support | |
1070 | @item | |
1071 | Floppy drive | |
e80cfcfc FB |
1072 | @end itemize |
1073 | ||
3475187d FB |
1074 | The number of peripherals is fixed in the architecture. |
1075 | ||
e80cfcfc | 1076 | QEMU uses the Proll, a PROM replacement available at |
3475187d FB |
1077 | @url{http://people.redhat.com/zaitcev/linux/}. The required |
1078 | QEMU-specific patches are included with the sources. | |
1079 | ||
1080 | A sample Linux 2.6 series kernel and ram disk image are available on | |
1081 | the QEMU web site. Please note that currently neither Linux 2.4 | |
1082 | series, NetBSD, nor OpenBSD kernels work. | |
1083 | ||
1084 | @c man begin OPTIONS | |
1085 | ||
1086 | The following options are specific to the Sparc emulation: | |
1087 | ||
1088 | @table @option | |
1089 | ||
1090 | @item -g WxH | |
1091 | ||
1092 | Set the initial TCX graphic mode. The default is 1024x768. | |
1093 | ||
1094 | @end table | |
1095 | ||
1096 | @c man end | |
1097 | ||
1098 | @chapter Sparc64 System emulator invocation | |
e80cfcfc | 1099 | |
3475187d FB |
1100 | Use the executable @file{qemu-system-sparc64} to simulate a Sun4u machine. |
1101 | The emulator is not usable for anything yet. | |
b756921a | 1102 | |
83469015 FB |
1103 | QEMU emulates the following sun4u peripherals: |
1104 | ||
1105 | @itemize @minus | |
1106 | @item | |
1107 | UltraSparc IIi APB PCI Bridge | |
1108 | @item | |
1109 | PCI VGA compatible card with VESA Bochs Extensions | |
1110 | @item | |
1111 | Non Volatile RAM M48T59 | |
1112 | @item | |
1113 | PC-compatible serial ports | |
1114 | @end itemize | |
1115 | ||
9d0a8e6f FB |
1116 | @chapter MIPS System emulator invocation |
1117 | ||
1118 | Use the executable @file{qemu-system-mips} to simulate a MIPS machine. | |
1119 | The emulator begins to launch a Linux kernel. | |
1120 | ||
1f673135 | 1121 | @chapter QEMU User space emulator invocation |
386405f7 | 1122 | |
1f673135 | 1123 | @section Quick Start |
df0f11a0 | 1124 | |
1f673135 FB |
1125 | In order to launch a Linux process, QEMU needs the process executable |
1126 | itself and all the target (x86) dynamic libraries used by it. | |
386405f7 | 1127 | |
1f673135 | 1128 | @itemize |
386405f7 | 1129 | |
1f673135 FB |
1130 | @item On x86, you can just try to launch any process by using the native |
1131 | libraries: | |
386405f7 | 1132 | |
1f673135 FB |
1133 | @example |
1134 | qemu-i386 -L / /bin/ls | |
1135 | @end example | |
386405f7 | 1136 | |
1f673135 FB |
1137 | @code{-L /} tells that the x86 dynamic linker must be searched with a |
1138 | @file{/} prefix. | |
386405f7 | 1139 | |
1f673135 | 1140 | @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): |
386405f7 | 1141 | |
1f673135 FB |
1142 | @example |
1143 | qemu-i386 -L / qemu-i386 -L / /bin/ls | |
1144 | @end example | |
386405f7 | 1145 | |
1f673135 FB |
1146 | @item On non x86 CPUs, you need first to download at least an x86 glibc |
1147 | (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that | |
1148 | @code{LD_LIBRARY_PATH} is not set: | |
df0f11a0 | 1149 | |
1f673135 FB |
1150 | @example |
1151 | unset LD_LIBRARY_PATH | |
1152 | @end example | |
1eb87257 | 1153 | |
1f673135 | 1154 | Then you can launch the precompiled @file{ls} x86 executable: |
1eb87257 | 1155 | |
1f673135 FB |
1156 | @example |
1157 | qemu-i386 tests/i386/ls | |
1158 | @end example | |
1159 | You can look at @file{qemu-binfmt-conf.sh} so that | |
1160 | QEMU is automatically launched by the Linux kernel when you try to | |
1161 | launch x86 executables. It requires the @code{binfmt_misc} module in the | |
1162 | Linux kernel. | |
1eb87257 | 1163 | |
1f673135 FB |
1164 | @item The x86 version of QEMU is also included. You can try weird things such as: |
1165 | @example | |
1166 | qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | |
1167 | @end example | |
1eb20527 | 1168 | |
1f673135 | 1169 | @end itemize |
1eb20527 | 1170 | |
1f673135 | 1171 | @section Wine launch |
1eb20527 | 1172 | |
1f673135 | 1173 | @itemize |
386405f7 | 1174 | |
1f673135 FB |
1175 | @item Ensure that you have a working QEMU with the x86 glibc |
1176 | distribution (see previous section). In order to verify it, you must be | |
1177 | able to do: | |
386405f7 | 1178 | |
1f673135 FB |
1179 | @example |
1180 | qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | |
1181 | @end example | |
386405f7 | 1182 | |
1f673135 FB |
1183 | @item Download the binary x86 Wine install |
1184 | (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). | |
386405f7 | 1185 | |
1f673135 FB |
1186 | @item Configure Wine on your account. Look at the provided script |
1187 | @file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous | |
1188 | @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}. | |
386405f7 | 1189 | |
1f673135 | 1190 | @item Then you can try the example @file{putty.exe}: |
386405f7 | 1191 | |
1f673135 FB |
1192 | @example |
1193 | qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe | |
1194 | @end example | |
386405f7 | 1195 | |
1f673135 | 1196 | @end itemize |
fd429f2f | 1197 | |
1f673135 | 1198 | @section Command line options |
1eb20527 | 1199 | |
1f673135 FB |
1200 | @example |
1201 | usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] | |
1202 | @end example | |
1eb20527 | 1203 | |
1f673135 FB |
1204 | @table @option |
1205 | @item -h | |
1206 | Print the help | |
1207 | @item -L path | |
1208 | Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | |
1209 | @item -s size | |
1210 | Set the x86 stack size in bytes (default=524288) | |
386405f7 FB |
1211 | @end table |
1212 | ||
1f673135 | 1213 | Debug options: |
386405f7 | 1214 | |
1f673135 FB |
1215 | @table @option |
1216 | @item -d | |
1217 | Activate log (logfile=/tmp/qemu.log) | |
1218 | @item -p pagesize | |
1219 | Act as if the host page size was 'pagesize' bytes | |
1220 | @end table | |
386405f7 | 1221 | |
15a34c63 FB |
1222 | @node compilation |
1223 | @chapter Compilation from the sources | |
1224 | ||
7c3fc84d FB |
1225 | @section Linux/Unix |
1226 | ||
1227 | @subsection Compilation | |
1228 | ||
1229 | First you must decompress the sources: | |
1230 | @example | |
1231 | cd /tmp | |
1232 | tar zxvf qemu-x.y.z.tar.gz | |
1233 | cd qemu-x.y.z | |
1234 | @end example | |
1235 | ||
1236 | Then you configure QEMU and build it (usually no options are needed): | |
1237 | @example | |
1238 | ./configure | |
1239 | make | |
1240 | @end example | |
1241 | ||
1242 | Then type as root user: | |
1243 | @example | |
1244 | make install | |
1245 | @end example | |
1246 | to install QEMU in @file{/usr/local}. | |
1247 | ||
7c3fc84d FB |
1248 | @subsection Tested tool versions |
1249 | ||
1250 | In order to compile QEMU succesfully, it is very important that you | |
1251 | have the right tools. The most important one is gcc. I cannot guaranty | |
1252 | that QEMU works if you do not use a tested gcc version. Look at | |
1253 | 'configure' and 'Makefile' if you want to make a different gcc | |
1254 | version work. | |
1255 | ||
1256 | @example | |
1257 | host gcc binutils glibc linux distribution | |
1258 | ---------------------------------------------------------------------- | |
1259 | x86 3.2 2.13.2 2.1.3 2.4.18 | |
1260 | 2.96 2.11.93.0.2 2.2.5 2.4.18 Red Hat 7.3 | |
1261 | 3.2.2 2.13.90.0.18 2.3.2 2.4.20 Red Hat 9 | |
1262 | ||
1263 | PowerPC 3.3 [4] 2.13.90.0.18 2.3.1 2.4.20briq | |
1264 | 3.2 | |
1265 | ||
1266 | Alpha 3.3 [1] 2.14.90.0.4 2.2.5 2.2.20 [2] Debian 3.0 | |
1267 | ||
1268 | Sparc32 2.95.4 2.12.90.0.1 2.2.5 2.4.18 Debian 3.0 | |
1269 | ||
1270 | ARM 2.95.4 2.12.90.0.1 2.2.5 2.4.9 [3] Debian 3.0 | |
1271 | ||
1272 | [1] On Alpha, QEMU needs the gcc 'visibility' attribute only available | |
1273 | for gcc version >= 3.3. | |
1274 | [2] Linux >= 2.4.20 is necessary for precise exception support | |
1275 | (untested). | |
1276 | [3] 2.4.9-ac10-rmk2-np1-cerf2 | |
1277 | ||
1278 | [4] gcc 2.95.x generates invalid code when using too many register | |
1279 | variables. You must use gcc 3.x on PowerPC. | |
1280 | @end example | |
15a34c63 FB |
1281 | |
1282 | @section Windows | |
1283 | ||
1284 | @itemize | |
1285 | @item Install the current versions of MSYS and MinGW from | |
1286 | @url{http://www.mingw.org/}. You can find detailed installation | |
1287 | instructions in the download section and the FAQ. | |
1288 | ||
1289 | @item Download | |
1290 | the MinGW development library of SDL 1.2.x | |
1291 | (@file{SDL-devel-1.2.x-mingw32.tar.gz}) from | |
1292 | @url{http://www.libsdl.org}. Unpack it in a temporary place, and | |
1293 | unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool | |
1294 | directory. Edit the @file{sdl-config} script so that it gives the | |
1295 | correct SDL directory when invoked. | |
1296 | ||
1297 | @item Extract the current version of QEMU. | |
1298 | ||
1299 | @item Start the MSYS shell (file @file{msys.bat}). | |
1300 | ||
1301 | @item Change to the QEMU directory. Launch @file{./configure} and | |
1302 | @file{make}. If you have problems using SDL, verify that | |
1303 | @file{sdl-config} can be launched from the MSYS command line. | |
1304 | ||
1305 | @item You can install QEMU in @file{Program Files/Qemu} by typing | |
1306 | @file{make install}. Don't forget to copy @file{SDL.dll} in | |
1307 | @file{Program Files/Qemu}. | |
1308 | ||
1309 | @end itemize | |
1310 | ||
1311 | @section Cross compilation for Windows with Linux | |
1312 | ||
1313 | @itemize | |
1314 | @item | |
1315 | Install the MinGW cross compilation tools available at | |
1316 | @url{http://www.mingw.org/}. | |
1317 | ||
1318 | @item | |
1319 | Install the Win32 version of SDL (@url{http://www.libsdl.org}) by | |
1320 | unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment | |
1321 | variable so that @file{i386-mingw32msvc-sdl-config} can be launched by | |
1322 | the QEMU configuration script. | |
1323 | ||
1324 | @item | |
1325 | Configure QEMU for Windows cross compilation: | |
1326 | @example | |
1327 | ./configure --enable-mingw32 | |
1328 | @end example | |
1329 | If necessary, you can change the cross-prefix according to the prefix | |
1330 | choosen for the MinGW tools with --cross-prefix. You can also use | |
1331 | --prefix to set the Win32 install path. | |
1332 | ||
1333 | @item You can install QEMU in the installation directory by typing | |
1334 | @file{make install}. Don't forget to copy @file{SDL.dll} in the | |
1335 | installation directory. | |
1336 | ||
1337 | @end itemize | |
1338 | ||
1339 | Note: Currently, Wine does not seem able to launch | |
1340 | QEMU for Win32. | |
1341 | ||
1342 | @section Mac OS X | |
1343 | ||
1344 | The Mac OS X patches are not fully merged in QEMU, so you should look | |
1345 | at the QEMU mailing list archive to have all the necessary | |
1346 | information. | |
1347 |