]>
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 FB |
24 | Full system emulation. In this mode, QEMU emulates a full system (for |
25 | example a PC), including a processor and various peripherials. It can | |
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 | ||
1f673135 | 37 | As QEMU requires no host kernel driver to run, it is very safe and |
1eb20527 | 38 | easy to use. |
322d0c66 | 39 | |
52c00a5f FB |
40 | For system emulation, the following hardware targets are supported: |
41 | @itemize | |
42 | @item PC (x86 processor) | |
43 | @item PREP (PowerPC processor) | |
44 | @end itemize | |
386405f7 | 45 | |
1f673135 | 46 | For user emulation, x86, PowerPC, ARM, and SPARC CPUs are supported. |
0806e3f6 | 47 | |
5b9f457a FB |
48 | @chapter Installation |
49 | ||
1f673135 FB |
50 | @section Linux |
51 | ||
5b9f457a FB |
52 | If you want to compile QEMU, please read the @file{README} which gives |
53 | the related information. Otherwise just download the binary | |
54 | distribution (@file{qemu-XXX-i386.tar.gz}) and untar it as root in | |
55 | @file{/}: | |
56 | ||
57 | @example | |
58 | su | |
59 | cd / | |
60 | tar zxvf /tmp/qemu-XXX-i386.tar.gz | |
61 | @end example | |
62 | ||
1f673135 | 63 | @section Windows |
8cd0ac2f | 64 | |
d691f669 | 65 | @itemize |
1f673135 FB |
66 | @item Install the current versions of MSYS and MinGW from |
67 | @url{http://www.mingw.org/}. You can find detailed installation | |
68 | instructions in the download section and the FAQ. | |
69 | ||
70 | @item Download | |
71 | the MinGW development library of SDL 1.2.x | |
72 | (@file{SDL-devel-1.2.x-mingw32.tar.gz}) from | |
73 | @url{http://www.libsdl.org}. Unpack it in a temporary place, and | |
74 | unpack the archive @file{i386-mingw32msvc.tar.gz} in the MinGW tool | |
75 | directory. Edit the @file{sdl-config} script so that it gives the | |
76 | correct SDL directory when invoked. | |
77 | ||
78 | @item Extract the current version of QEMU. | |
79 | ||
80 | @item Start the MSYS shell (file @file{msys.bat}). | |
386405f7 | 81 | |
1f673135 FB |
82 | @item Change to the QEMU directory. Launch @file{./configure} and |
83 | @file{make}. If you have problems using SDL, verify that | |
84 | @file{sdl-config} can be launched from the MSYS command line. | |
644c433c | 85 | |
1f673135 FB |
86 | @item You can install QEMU in @file{Program Files/Qemu} by typing |
87 | @file{make install}. Don't forget to copy @file{SDL.dll} in | |
88 | @file{Program Files/Qemu}. | |
1eb87257 | 89 | |
168485b7 FB |
90 | @end itemize |
91 | ||
1f673135 | 92 | @section Cross compilation for Windows with Linux |
168485b7 FB |
93 | |
94 | @itemize | |
1f673135 FB |
95 | @item |
96 | Install the MinGW cross compilation tools available at | |
97 | @url{http://www.mingw.org/}. | |
168485b7 | 98 | |
1f673135 FB |
99 | @item |
100 | Install the Win32 version of SDL (@url{http://www.libsdl.org}) by | |
101 | unpacking @file{i386-mingw32msvc.tar.gz}. Set up the PATH environment | |
102 | variable so that @file{i386-mingw32msvc-sdl-config} can be launched by | |
103 | the QEMU configuration script. | |
168485b7 | 104 | |
1f673135 FB |
105 | @item |
106 | Configure QEMU for Windows cross compilation: | |
168485b7 | 107 | @example |
1f673135 | 108 | ./configure --enable-mingw32 |
168485b7 | 109 | @end example |
1f673135 FB |
110 | If necessary, you can change the cross-prefix according to the prefix |
111 | choosen for the MinGW tools with --cross-prefix. You can also use | |
112 | --prefix to set the Win32 install path. | |
168485b7 | 113 | |
1f673135 FB |
114 | @item You can install QEMU in the installation directory by typing |
115 | @file{make install}. Don't forget to copy @file{SDL.dll} in the | |
116 | installation directory. | |
d691f669 FB |
117 | |
118 | @end itemize | |
119 | ||
1f673135 FB |
120 | Note: Currently, Wine does not seem able to launch |
121 | QEMU for Win32. | |
d691f669 | 122 | |
1f673135 | 123 | @section Mac OS X |
d691f669 | 124 | |
1f673135 | 125 | Mac OS X is currently not supported. |
df0f11a0 | 126 | |
52c00a5f | 127 | @chapter QEMU PC System emulator invocation |
1eb20527 | 128 | |
0806e3f6 FB |
129 | @section Introduction |
130 | ||
131 | @c man begin DESCRIPTION | |
132 | ||
52c00a5f | 133 | The QEMU System emulator simulates a complete PC. |
0806e3f6 FB |
134 | |
135 | In order to meet specific user needs, two versions of QEMU are | |
136 | available: | |
137 | ||
138 | @enumerate | |
139 | ||
140 | @item | |
285dc330 | 141 | @code{qemu-fast} uses the host Memory Management Unit (MMU) to simulate |
0806e3f6 FB |
142 | the x86 MMU. It is @emph{fast} but has limitations because the whole 4 GB |
143 | address space cannot be used and some memory mapped peripherials | |
144 | cannot be emulated accurately yet. Therefore, a specific Linux kernel | |
145 | must be used (@xref{linux_compile}). | |
146 | ||
147 | @item | |
285dc330 FB |
148 | @code{qemu} uses a software MMU. It is about @emph{two times |
149 | slower} but gives a more accurate emulation. | |
0806e3f6 FB |
150 | |
151 | @end enumerate | |
152 | ||
153 | QEMU emulates the following PC peripherials: | |
154 | ||
155 | @itemize @minus | |
156 | @item | |
157 | VGA (hardware level, including all non standard modes) | |
158 | @item | |
159 | PS/2 mouse and keyboard | |
160 | @item | |
181f1558 | 161 | 2 IDE interfaces with hard disk and CD-ROM support |
1f673135 FB |
162 | @item |
163 | Floppy disk | |
0806e3f6 | 164 | @item |
1f673135 | 165 | up to 6 NE2000 network adapters |
0806e3f6 | 166 | @item |
181f1558 FB |
167 | Serial port |
168 | @item | |
169 | Soundblaster 16 card | |
0806e3f6 FB |
170 | @end itemize |
171 | ||
172 | @c man end | |
173 | ||
1eb20527 FB |
174 | @section Quick Start |
175 | ||
285dc330 | 176 | Download and uncompress the linux image (@file{linux.img}) and type: |
0806e3f6 FB |
177 | |
178 | @example | |
285dc330 | 179 | qemu linux.img |
0806e3f6 FB |
180 | @end example |
181 | ||
182 | Linux should boot and give you a prompt. | |
183 | ||
ec410fc9 FB |
184 | @section Invocation |
185 | ||
186 | @example | |
0806e3f6 FB |
187 | @c man begin SYNOPSIS |
188 | usage: qemu [options] [disk_image] | |
189 | @c man end | |
ec410fc9 FB |
190 | @end example |
191 | ||
0806e3f6 | 192 | @c man begin OPTIONS |
9d4520d0 | 193 | @var{disk_image} is a raw hard disk image for IDE hard disk 0. |
ec410fc9 FB |
194 | |
195 | General options: | |
196 | @table @option | |
2be3bc02 FB |
197 | @item -fda file |
198 | @item -fdb file | |
be3edd95 FB |
199 | Use @var{file} as floppy disk 0/1 image (@xref{disk_images}). You can |
200 | use the host floppy by using @file{/dev/fd0} as filename. | |
2be3bc02 | 201 | |
ec410fc9 FB |
202 | @item -hda file |
203 | @item -hdb file | |
181f1558 FB |
204 | @item -hdc file |
205 | @item -hdd file | |
2be3bc02 | 206 | Use @var{file} as hard disk 0, 1, 2 or 3 image (@xref{disk_images}). |
1f47a922 | 207 | |
181f1558 FB |
208 | @item -cdrom file |
209 | Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and and | |
be3edd95 FB |
210 | @option{-cdrom} at the same time). You can use the host CD-ROM by |
211 | using @file{/dev/cdrom} as filename. | |
181f1558 | 212 | |
1f673135 FB |
213 | @item -boot [a|c|d] |
214 | Boot on floppy (a), hard disk (c) or CD-ROM (d). Hard disk boot is | |
2be3bc02 | 215 | the default. |
1f47a922 | 216 | |
181f1558 | 217 | @item -snapshot |
1f47a922 FB |
218 | Write to temporary files instead of disk image files. In this case, |
219 | the raw disk image you use is not written back. You can however force | |
220 | the write back by pressing @key{C-a s} (@xref{disk_images}). | |
ec410fc9 FB |
221 | |
222 | @item -m megs | |
223 | Set virtual RAM size to @var{megs} megabytes. | |
224 | ||
4690764b | 225 | @item -initrd file |
0806e3f6 FB |
226 | Use @var{file} as initial ram disk. |
227 | ||
0806e3f6 FB |
228 | @item -nographic |
229 | ||
230 | Normally, QEMU uses SDL to display the VGA output. With this option, | |
231 | you can totally disable graphical output so that QEMU is a simple | |
232 | command line application. The emulated serial port is redirected on | |
233 | the console. Therefore, you can still use QEMU to debug a Linux kernel | |
234 | with a serial console. | |
235 | ||
a8c490cd FB |
236 | @item -enable-audio |
237 | ||
238 | The SB16 emulation is disabled by default as it may give problems with | |
239 | Windows. You can enable it manually with this option. | |
240 | ||
0806e3f6 FB |
241 | @end table |
242 | ||
1f673135 FB |
243 | Network options: |
244 | ||
245 | @table @option | |
246 | ||
247 | @item -n script | |
52c00a5f FB |
248 | Set TUN/TAP network init script [default=/etc/qemu-ifup]. This script |
249 | is launched to configure the host network interface (usually tun0) | |
1f673135 FB |
250 | corresponding to the virtual NE2000 card. |
251 | ||
1f673135 FB |
252 | @item -macaddr addr |
253 | ||
254 | Set the mac address of the first interface (the format is | |
255 | aa:bb:cc:dd:ee:ff in hexa). The mac address is incremented for each | |
256 | new network interface. | |
257 | ||
52c00a5f FB |
258 | @item -tun-fd fd |
259 | Assumes @var{fd} talks to a tap/tun host network interface and use | |
260 | it. Read @url{http://bellard.org/qemu/tetrinet.html} to have an | |
261 | example of its use. | |
262 | ||
263 | @item -user-net | |
264 | (Experimental) Use the user mode network stack. This is the default if | |
265 | no tun/tap network init script is found. | |
266 | ||
267 | @item -dummy-net | |
268 | Use the dummy network stack: no packet will be received on the network | |
269 | cards. | |
1f673135 FB |
270 | |
271 | @end table | |
272 | ||
273 | Linux boot specific. When using this options, you can use a given | |
274 | Linux kernel without installing it in the disk image. It can be useful | |
275 | for easier testing of various kernels. | |
276 | ||
0806e3f6 FB |
277 | @table @option |
278 | ||
279 | @item -kernel bzImage | |
280 | Use @var{bzImage} as kernel image. | |
281 | ||
282 | @item -append cmdline | |
283 | Use @var{cmdline} as kernel command line | |
284 | ||
285 | @item -initrd file | |
286 | Use @var{file} as initial ram disk. | |
287 | ||
ec410fc9 FB |
288 | @end table |
289 | ||
290 | Debug options: | |
291 | @table @option | |
292 | @item -s | |
0806e3f6 | 293 | Wait gdb connection to port 1234 (@xref{gdb_usage}). |
ec410fc9 FB |
294 | @item -p port |
295 | Change gdb connection port. | |
52c00a5f FB |
296 | @item -S |
297 | Do not start CPU at startup (you must type 'c' in the monitor). | |
ec410fc9 | 298 | @item -d |
9d4520d0 | 299 | Output log in /tmp/qemu.log |
ec410fc9 FB |
300 | @end table |
301 | ||
a1b74fe8 FB |
302 | During the graphical emulation, you can use the following keys: |
303 | @table @key | |
10d315a8 | 304 | @item Ctrl-Shift |
a1b74fe8 | 305 | Toggle mouse and keyboard grab. |
10d315a8 | 306 | @item Ctrl-Shift-f |
a1b74fe8 FB |
307 | Toggle full screen |
308 | @end table | |
309 | ||
1f673135 FB |
310 | During emulation, if you are using the serial console, use @key{C-a h} |
311 | to get terminal commands: | |
ec410fc9 FB |
312 | |
313 | @table @key | |
a1b74fe8 | 314 | @item Ctrl-a h |
ec410fc9 | 315 | Print this help |
a1b74fe8 | 316 | @item Ctrl-a x |
ec410fc9 | 317 | Exit emulatior |
a1b74fe8 | 318 | @item Ctrl-a s |
1f47a922 | 319 | Save disk data back to file (if -snapshot) |
a1b74fe8 | 320 | @item Ctrl-a b |
1f673135 | 321 | Send break (magic sysrq in Linux) |
a1b74fe8 | 322 | @item Ctrl-a c |
1f673135 | 323 | Switch between console and monitor |
a1b74fe8 FB |
324 | @item Ctrl-a Ctrl-a |
325 | Send Ctrl-a | |
ec410fc9 | 326 | @end table |
0806e3f6 FB |
327 | @c man end |
328 | ||
329 | @ignore | |
330 | ||
331 | @setfilename qemu | |
332 | @settitle QEMU System Emulator | |
333 | ||
1f673135 FB |
334 | @c man begin SEEALSO |
335 | The HTML documentation of QEMU for more precise information and Linux | |
336 | user mode emulator invocation. | |
337 | @c man end | |
338 | ||
339 | @c man begin AUTHOR | |
340 | Fabrice Bellard | |
341 | @c man end | |
342 | ||
343 | @end ignore | |
344 | ||
345 | @end ignore | |
346 | ||
347 | ||
348 | @section QEMU Monitor | |
349 | ||
350 | The QEMU monitor is used to give complex commands to the QEMU | |
351 | emulator. You can use it to: | |
352 | ||
353 | @itemize @minus | |
354 | ||
355 | @item | |
356 | Remove or insert removable medias images | |
357 | (such as CD-ROM or floppies) | |
358 | ||
359 | @item | |
360 | Freeze/unfreeze the Virtual Machine (VM) and save or restore its state | |
361 | from a disk file. | |
362 | ||
363 | @item Inspect the VM state without an external debugger. | |
364 | ||
365 | @end itemize | |
366 | ||
367 | @subsection Commands | |
368 | ||
369 | The following commands are available: | |
370 | ||
371 | @table @option | |
372 | ||
373 | @item help or ? [cmd] | |
374 | Show the help for all commands or just for command @var{cmd}. | |
375 | ||
376 | @item commit | |
377 | Commit changes to the disk images (if -snapshot is used) | |
378 | ||
379 | @item info subcommand | |
380 | show various information about the system state | |
381 | ||
382 | @table @option | |
383 | @item info network | |
384 | show the network state | |
385 | @item info block | |
386 | show the block devices | |
387 | @item info registers | |
388 | show the cpu registers | |
389 | @item info history | |
390 | show the command line history | |
391 | @end table | |
392 | ||
393 | @item q or quit | |
394 | Quit the emulator. | |
395 | ||
396 | @item eject [-f] device | |
397 | Eject a removable media (use -f to force it). | |
398 | ||
399 | @item change device filename | |
400 | Change a removable media. | |
401 | ||
402 | @item screendump filename | |
403 | Save screen into PPM image @var{filename}. | |
404 | ||
405 | @item log item1[,...] | |
406 | Activate logging of the specified items to @file{/tmp/qemu.log}. | |
407 | ||
408 | @item savevm filename | |
409 | Save the whole virtual machine state to @var{filename}. | |
410 | ||
411 | @item loadvm filename | |
412 | Restore the whole virtual machine state from @var{filename}. | |
413 | ||
414 | @item stop | |
415 | Stop emulation. | |
416 | ||
417 | @item c or cont | |
418 | Resume emulation. | |
419 | ||
420 | @item gdbserver [port] | |
421 | Start gdbserver session (default port=1234) | |
422 | ||
423 | @item x/fmt addr | |
424 | Virtual memory dump starting at @var{addr}. | |
425 | ||
426 | @item xp /fmt addr | |
427 | Physical memory dump starting at @var{addr}. | |
428 | ||
429 | @var{fmt} is a format which tells the command how to format the | |
430 | data. Its syntax is: @option{/@{count@}@{format@}@{size@}} | |
431 | ||
432 | @table @var | |
433 | @item count | |
434 | is the number of items to be dumped. | |
435 | ||
436 | @item format | |
437 | can be x (hexa), d (signed decimal), u (unsigned decimal), o (octal), | |
438 | c (char) or i (asm instruction). | |
439 | ||
440 | @item size | |
52c00a5f FB |
441 | can be b (8 bits), h (16 bits), w (32 bits) or g (64 bits). On x86, |
442 | @code{h} or @code{w} can be specified with the @code{i} format to | |
443 | respectively select 16 or 32 bit code instruction size. | |
1f673135 FB |
444 | |
445 | @end table | |
446 | ||
447 | Examples: | |
448 | @itemize | |
449 | @item | |
450 | Dump 10 instructions at the current instruction pointer: | |
451 | @example | |
452 | (qemu) x/10i $eip | |
453 | 0x90107063: ret | |
454 | 0x90107064: sti | |
455 | 0x90107065: lea 0x0(%esi,1),%esi | |
456 | 0x90107069: lea 0x0(%edi,1),%edi | |
457 | 0x90107070: ret | |
458 | 0x90107071: jmp 0x90107080 | |
459 | 0x90107073: nop | |
460 | 0x90107074: nop | |
461 | 0x90107075: nop | |
462 | 0x90107076: nop | |
463 | @end example | |
464 | ||
465 | @item | |
466 | Dump 80 16 bit values at the start of the video memory. | |
467 | @example | |
468 | (qemu) xp/80hx 0xb8000 | |
469 | 0x000b8000: 0x0b50 0x0b6c 0x0b65 0x0b78 0x0b38 0x0b36 0x0b2f 0x0b42 | |
470 | 0x000b8010: 0x0b6f 0x0b63 0x0b68 0x0b73 0x0b20 0x0b56 0x0b47 0x0b41 | |
471 | 0x000b8020: 0x0b42 0x0b69 0x0b6f 0x0b73 0x0b20 0x0b63 0x0b75 0x0b72 | |
472 | 0x000b8030: 0x0b72 0x0b65 0x0b6e 0x0b74 0x0b2d 0x0b63 0x0b76 0x0b73 | |
473 | 0x000b8040: 0x0b20 0x0b30 0x0b35 0x0b20 0x0b4e 0x0b6f 0x0b76 0x0b20 | |
474 | 0x000b8050: 0x0b32 0x0b30 0x0b30 0x0b33 0x0720 0x0720 0x0720 0x0720 | |
475 | 0x000b8060: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
476 | 0x000b8070: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
477 | 0x000b8080: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
478 | 0x000b8090: 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 0x0720 | |
479 | @end example | |
480 | @end itemize | |
481 | ||
482 | @item p or print/fmt expr | |
483 | ||
484 | Print expression value. Only the @var{format} part of @var{fmt} is | |
485 | used. | |
0806e3f6 | 486 | |
1f673135 | 487 | @end table |
0806e3f6 | 488 | |
1f673135 FB |
489 | @subsection Integer expressions |
490 | ||
491 | The monitor understands integers expressions for every integer | |
492 | argument. You can use register names to get the value of specifics | |
493 | CPU registers by prefixing them with @emph{$}. | |
ec410fc9 | 494 | |
1f47a922 FB |
495 | @node disk_images |
496 | @section Disk Images | |
497 | ||
498 | @subsection Raw disk images | |
499 | ||
500 | The disk images can simply be raw images of the hard disk. You can | |
501 | create them with the command: | |
502 | @example | |
a1b74fe8 | 503 | dd of=myimage bs=1024 seek=mysize count=0 |
1f47a922 FB |
504 | @end example |
505 | where @var{myimage} is the image filename and @var{mysize} is its size | |
506 | in kilobytes. | |
507 | ||
508 | @subsection Snapshot mode | |
509 | ||
510 | If you use the option @option{-snapshot}, all disk images are | |
511 | considered as read only. When sectors in written, they are written in | |
512 | a temporary file created in @file{/tmp}. You can however force the | |
513 | write back to the raw disk images by pressing @key{C-a s}. | |
514 | ||
515 | NOTE: The snapshot mode only works with raw disk images. | |
516 | ||
517 | @subsection Copy On Write disk images | |
518 | ||
519 | QEMU also supports user mode Linux | |
520 | (@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW) | |
521 | disk images. The COW disk images are much smaller than normal images | |
522 | as they store only modified sectors. They also permit the use of the | |
523 | same disk image template for many users. | |
524 | ||
525 | To create a COW disk images, use the command: | |
526 | ||
527 | @example | |
0806e3f6 | 528 | qemu-mkcow -f myrawimage.bin mycowimage.cow |
1f47a922 FB |
529 | @end example |
530 | ||
531 | @file{myrawimage.bin} is a raw image you want to use as original disk | |
532 | image. It will never be written to. | |
533 | ||
534 | @file{mycowimage.cow} is the COW disk image which is created by | |
0806e3f6 | 535 | @code{qemu-mkcow}. You can use it directly with the @option{-hdx} |
1f47a922 FB |
536 | options. You must not modify the original raw disk image if you use |
537 | COW images, as COW images only store the modified sectors from the raw | |
538 | disk image. QEMU stores the original raw disk image name and its | |
539 | modified time in the COW disk image so that chances of mistakes are | |
540 | reduced. | |
541 | ||
9d0fe224 FB |
542 | If the raw disk image is not read-only, by pressing @key{C-a s} you |
543 | can flush the COW disk image back into the raw disk image, as in | |
544 | snapshot mode. | |
1f47a922 FB |
545 | |
546 | COW disk images can also be created without a corresponding raw disk | |
547 | image. It is useful to have a big initial virtual disk image without | |
548 | using much disk space. Use: | |
549 | ||
550 | @example | |
0806e3f6 | 551 | qemu-mkcow mycowimage.cow 1024 |
1f47a922 FB |
552 | @end example |
553 | ||
554 | to create a 1 gigabyte empty COW disk image. | |
555 | ||
556 | NOTES: | |
557 | @enumerate | |
558 | @item | |
559 | COW disk images must be created on file systems supporting | |
560 | @emph{holes} such as ext2 or ext3. | |
561 | @item | |
562 | Since holes are used, the displayed size of the COW disk image is not | |
563 | the real one. To know it, use the @code{ls -ls} command. | |
564 | @end enumerate | |
565 | ||
9d4fb82e FB |
566 | @section Network emulation |
567 | ||
568 | QEMU simulates up to 6 networks cards (NE2000 boards). Each card can | |
569 | be connected to a specific host network interface. | |
570 | ||
571 | @subsection Using tun/tap network interface | |
572 | ||
573 | This is the standard way to emulate network. QEMU adds a virtual | |
574 | network device on your host (called @code{tun0}), and you can then | |
575 | configure it as if it was a real ethernet card. | |
576 | ||
577 | As an example, you can download the @file{linux-test-xxx.tar.gz} | |
578 | archive and copy the script @file{qemu-ifup} in @file{/etc} and | |
579 | configure properly @code{sudo} so that the command @code{ifconfig} | |
580 | contained in @file{qemu-ifup} can be executed as root. You must verify | |
581 | that your host kernel supports the TUN/TAP network interfaces: the | |
582 | device @file{/dev/net/tun} must be present. | |
583 | ||
584 | See @ref{direct_linux_boot} to have an example of network use with a | |
585 | Linux distribution. | |
586 | ||
587 | @subsection Using the user mode network stack | |
588 | ||
589 | This is @emph{experimental} (version 0.5.4). You must configure qemu | |
590 | with @code{--enable-slirp}. Then by using the option | |
591 | @option{-user-net} or if you have no tun/tap init script, QEMU uses a | |
592 | completely user mode network stack (you don't need root priviledge to | |
593 | use the virtual network). The virtual network configuration is the | |
594 | following: | |
595 | ||
596 | @example | |
597 | ||
598 | QEMU Virtual Machine <------> Firewall/DHCP server <-----> Internet | |
599 | (10.0.2.x) | (10.0.2.2) | |
600 | | | |
601 | ----> DNS | |
602 | (10.0.2.3) | |
603 | @end example | |
604 | ||
605 | The QEMU VM behaves as if it was behind a firewall which blocks all | |
606 | incoming connections. You can use a DHCP client to automatically | |
607 | configure the network in the QEMU VM. | |
608 | ||
609 | In order to check that the user mode network is working, you can ping | |
610 | the address 10.0.2.2 and verify that you got an address in the range | |
611 | 10.0.2.x from the QEMU virtual DHCP server. | |
612 | ||
b415a407 FB |
613 | Note that @code{ping} is not supported reliably to the internet as it |
614 | would require root priviledges. It means you can only ping the local | |
615 | router (10.0.2.2). | |
616 | ||
9d4fb82e FB |
617 | @node direct_linux_boot |
618 | @section Direct Linux Boot | |
1f673135 FB |
619 | |
620 | This section explains how to launch a Linux kernel inside QEMU without | |
621 | having to make a full bootable image. It is very useful for fast Linux | |
622 | kernel testing. The QEMU network configuration is also explained. | |
623 | ||
624 | @enumerate | |
625 | @item | |
626 | Download the archive @file{linux-test-xxx.tar.gz} containing a Linux | |
627 | kernel and a disk image. | |
628 | ||
629 | @item Optional: If you want network support (for example to launch X11 examples), you | |
630 | must copy the script @file{qemu-ifup} in @file{/etc} and configure | |
631 | properly @code{sudo} so that the command @code{ifconfig} contained in | |
632 | @file{qemu-ifup} can be executed as root. You must verify that your host | |
633 | kernel supports the TUN/TAP network interfaces: the device | |
634 | @file{/dev/net/tun} must be present. | |
635 | ||
636 | When network is enabled, there is a virtual network connection between | |
637 | the host kernel and the emulated kernel. The emulated kernel is seen | |
638 | from the host kernel at IP address 172.20.0.2 and the host kernel is | |
639 | seen from the emulated kernel at IP address 172.20.0.1. | |
640 | ||
641 | @item Launch @code{qemu.sh}. You should have the following output: | |
642 | ||
643 | @example | |
644 | > ./qemu.sh | |
645 | Connected to host network interface: tun0 | |
646 | 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 | |
647 | BIOS-provided physical RAM map: | |
648 | BIOS-e801: 0000000000000000 - 000000000009f000 (usable) | |
649 | BIOS-e801: 0000000000100000 - 0000000002000000 (usable) | |
650 | 32MB LOWMEM available. | |
651 | On node 0 totalpages: 8192 | |
652 | zone(0): 4096 pages. | |
653 | zone(1): 4096 pages. | |
654 | zone(2): 0 pages. | |
655 | Kernel command line: root=/dev/hda sb=0x220,5,1,5 ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe console=ttyS0 | |
656 | ide_setup: ide2=noprobe | |
657 | ide_setup: ide3=noprobe | |
658 | ide_setup: ide4=noprobe | |
659 | ide_setup: ide5=noprobe | |
660 | Initializing CPU#0 | |
661 | Detected 2399.621 MHz processor. | |
662 | Console: colour EGA 80x25 | |
663 | Calibrating delay loop... 4744.80 BogoMIPS | |
664 | Memory: 28872k/32768k available (1210k kernel code, 3508k reserved, 266k data, 64k init, 0k highmem) | |
665 | Dentry cache hash table entries: 4096 (order: 3, 32768 bytes) | |
666 | Inode cache hash table entries: 2048 (order: 2, 16384 bytes) | |
667 | Mount cache hash table entries: 512 (order: 0, 4096 bytes) | |
668 | Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) | |
669 | Page-cache hash table entries: 8192 (order: 3, 32768 bytes) | |
670 | CPU: Intel Pentium Pro stepping 03 | |
671 | Checking 'hlt' instruction... OK. | |
672 | POSIX conformance testing by UNIFIX | |
673 | Linux NET4.0 for Linux 2.4 | |
674 | Based upon Swansea University Computer Society NET3.039 | |
675 | Initializing RT netlink socket | |
676 | apm: BIOS not found. | |
677 | Starting kswapd | |
678 | Journalled Block Device driver loaded | |
679 | Detected PS/2 Mouse Port. | |
680 | pty: 256 Unix98 ptys configured | |
681 | Serial driver version 5.05c (2001-07-08) with no serial options enabled | |
682 | ttyS00 at 0x03f8 (irq = 4) is a 16450 | |
683 | ne.c:v1.10 9/23/94 Donald Becker (becker@scyld.com) | |
684 | Last modified Nov 1, 2000 by Paul Gortmaker | |
685 | NE*000 ethercard probe at 0x300: 52 54 00 12 34 56 | |
686 | eth0: NE2000 found at 0x300, using IRQ 9. | |
687 | RAMDISK driver initialized: 16 RAM disks of 4096K size 1024 blocksize | |
688 | Uniform Multi-Platform E-IDE driver Revision: 7.00beta4-2.4 | |
689 | ide: Assuming 50MHz system bus speed for PIO modes; override with idebus=xx | |
690 | hda: QEMU HARDDISK, ATA DISK drive | |
691 | ide0 at 0x1f0-0x1f7,0x3f6 on irq 14 | |
692 | hda: attached ide-disk driver. | |
693 | hda: 20480 sectors (10 MB) w/256KiB Cache, CHS=20/16/63 | |
694 | Partition check: | |
695 | hda: | |
696 | Soundblaster audio driver Copyright (C) by Hannu Savolainen 1993-1996 | |
697 | NET4: Linux TCP/IP 1.0 for NET4.0 | |
698 | IP Protocols: ICMP, UDP, TCP, IGMP | |
699 | IP: routing cache hash table of 512 buckets, 4Kbytes | |
700 | TCP: Hash tables configured (established 2048 bind 4096) | |
701 | NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. | |
702 | EXT2-fs warning: mounting unchecked fs, running e2fsck is recommended | |
703 | VFS: Mounted root (ext2 filesystem). | |
704 | Freeing unused kernel memory: 64k freed | |
705 | ||
706 | 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 | |
707 | ||
708 | QEMU Linux test distribution (based on Redhat 9) | |
709 | ||
710 | Type 'exit' to halt the system | |
711 | ||
712 | sh-2.05b# | |
713 | @end example | |
714 | ||
715 | @item | |
716 | Then you can play with the kernel inside the virtual serial console. You | |
717 | can launch @code{ls} for example. Type @key{Ctrl-a h} to have an help | |
718 | about the keys you can type inside the virtual serial console. In | |
719 | particular, use @key{Ctrl-a x} to exit QEMU and use @key{Ctrl-a b} as | |
720 | the Magic SysRq key. | |
721 | ||
722 | @item | |
723 | If the network is enabled, launch the script @file{/etc/linuxrc} in the | |
724 | emulator (don't forget the leading dot): | |
725 | @example | |
726 | . /etc/linuxrc | |
727 | @end example | |
728 | ||
729 | Then enable X11 connections on your PC from the emulated Linux: | |
730 | @example | |
731 | xhost +172.20.0.2 | |
732 | @end example | |
733 | ||
734 | You can now launch @file{xterm} or @file{xlogo} and verify that you have | |
735 | a real Virtual Linux system ! | |
736 | ||
737 | @end enumerate | |
738 | ||
739 | NOTES: | |
740 | @enumerate | |
741 | @item | |
742 | A 2.5.74 kernel is also included in the archive. Just | |
743 | replace the bzImage in qemu.sh to try it. | |
744 | ||
745 | @item | |
746 | qemu-fast creates a temporary file in @var{$QEMU_TMPDIR} (@file{/tmp} is the | |
747 | default) containing all the simulated PC memory. If possible, try to use | |
748 | a temporary directory using the tmpfs filesystem to avoid too many | |
749 | unnecessary disk accesses. | |
750 | ||
751 | @item | |
752 | In order to exit cleanly from qemu, you can do a @emph{shutdown} inside | |
753 | qemu. qemu will automatically exit when the Linux shutdown is done. | |
754 | ||
755 | @item | |
756 | You can boot slightly faster by disabling the probe of non present IDE | |
757 | interfaces. To do so, add the following options on the kernel command | |
758 | line: | |
759 | @example | |
760 | ide1=noprobe ide2=noprobe ide3=noprobe ide4=noprobe ide5=noprobe | |
761 | @end example | |
762 | ||
763 | @item | |
764 | The example disk image is a modified version of the one made by Kevin | |
765 | Lawton for the plex86 Project (@url{www.plex86.org}). | |
766 | ||
767 | @end enumerate | |
768 | ||
0806e3f6 | 769 | @node linux_compile |
4690764b FB |
770 | @section Linux Kernel Compilation |
771 | ||
285dc330 | 772 | You can use any linux kernel with QEMU. However, if you want to use |
1f673135 FB |
773 | @code{qemu-fast} to get maximum performances, you must use a modified |
774 | guest kernel. If you are using a 2.6 guest kernel, you can use | |
775 | directly the patch @file{linux-2.6-qemu-fast.patch} made by Rusty | |
776 | Russel available in the QEMU source archive. Otherwise, you can make the | |
777 | following changes @emph{by hand} to the Linux kernel: | |
1eb20527 | 778 | |
4690764b FB |
779 | @enumerate |
780 | @item | |
781 | The kernel must be mapped at 0x90000000 (the default is | |
782 | 0xc0000000). You must modify only two lines in the kernel source: | |
1eb20527 | 783 | |
4690764b | 784 | In @file{include/asm/page.h}, replace |
1eb20527 FB |
785 | @example |
786 | #define __PAGE_OFFSET (0xc0000000) | |
787 | @end example | |
788 | by | |
789 | @example | |
790 | #define __PAGE_OFFSET (0x90000000) | |
791 | @end example | |
792 | ||
4690764b | 793 | And in @file{arch/i386/vmlinux.lds}, replace |
1eb20527 FB |
794 | @example |
795 | . = 0xc0000000 + 0x100000; | |
796 | @end example | |
797 | by | |
798 | @example | |
799 | . = 0x90000000 + 0x100000; | |
800 | @end example | |
801 | ||
4690764b FB |
802 | @item |
803 | If you want to enable SMP (Symmetric Multi-Processing) support, you | |
804 | must make the following change in @file{include/asm/fixmap.h}. Replace | |
1eb20527 | 805 | @example |
4690764b | 806 | #define FIXADDR_TOP (0xffffX000UL) |
1eb20527 | 807 | @end example |
4690764b FB |
808 | by |
809 | @example | |
810 | #define FIXADDR_TOP (0xa7ffX000UL) | |
811 | @end example | |
812 | (X is 'e' or 'f' depending on the kernel version). Although you can | |
813 | use an SMP kernel with QEMU, it only supports one CPU. | |
1eb20527 | 814 | |
4690764b | 815 | @item |
1f673135 FB |
816 | If you are not using a 2.6 kernel as host kernel but if you use a target |
817 | 2.6 kernel, you must also ensure that the 'HZ' define is set to 100 | |
d5a0b50c | 818 | (1000 is the default) as QEMU cannot currently emulate timers at |
1f673135 | 819 | frequencies greater than 100 Hz on host Linux systems < 2.6. In |
4690764b | 820 | @file{include/asm/param.h}, replace: |
d5a0b50c FB |
821 | |
822 | @example | |
823 | # define HZ 1000 /* Internal kernel timer frequency */ | |
824 | @end example | |
825 | by | |
826 | @example | |
827 | # define HZ 100 /* Internal kernel timer frequency */ | |
828 | @end example | |
829 | ||
4690764b FB |
830 | @end enumerate |
831 | ||
832 | The file config-2.x.x gives the configuration of the example kernels. | |
833 | ||
834 | Just type | |
835 | @example | |
836 | make bzImage | |
837 | @end example | |
838 | ||
839 | As you would do to make a real kernel. Then you can use with QEMU | |
840 | exactly the same kernel as you would boot on your PC (in | |
841 | @file{arch/i386/boot/bzImage}). | |
da415d54 | 842 | |
0806e3f6 | 843 | @node gdb_usage |
da415d54 FB |
844 | @section GDB usage |
845 | ||
846 | QEMU has a primitive support to work with gdb, so that you can do | |
0806e3f6 | 847 | 'Ctrl-C' while the virtual machine is running and inspect its state. |
da415d54 | 848 | |
9d4520d0 | 849 | In order to use gdb, launch qemu with the '-s' option. It will wait for a |
da415d54 FB |
850 | gdb connection: |
851 | @example | |
6c9bf893 | 852 | > qemu -s -kernel arch/i386/boot/bzImage -hda root-2.4.20.img -append "root=/dev/hda" |
da415d54 FB |
853 | Connected to host network interface: tun0 |
854 | Waiting gdb connection on port 1234 | |
855 | @end example | |
856 | ||
857 | Then launch gdb on the 'vmlinux' executable: | |
858 | @example | |
859 | > gdb vmlinux | |
860 | @end example | |
861 | ||
862 | In gdb, connect to QEMU: | |
863 | @example | |
6c9bf893 | 864 | (gdb) target remote localhost:1234 |
da415d54 FB |
865 | @end example |
866 | ||
867 | Then you can use gdb normally. For example, type 'c' to launch the kernel: | |
868 | @example | |
869 | (gdb) c | |
870 | @end example | |
871 | ||
0806e3f6 FB |
872 | Here are some useful tips in order to use gdb on system code: |
873 | ||
874 | @enumerate | |
875 | @item | |
876 | Use @code{info reg} to display all the CPU registers. | |
877 | @item | |
878 | Use @code{x/10i $eip} to display the code at the PC position. | |
879 | @item | |
880 | Use @code{set architecture i8086} to dump 16 bit code. Then use | |
881 | @code{x/10i $cs*16+*eip} to dump the code at the PC position. | |
882 | @end enumerate | |
883 | ||
1a084f3d FB |
884 | @section Target OS specific information |
885 | ||
886 | @subsection Linux | |
887 | ||
888 | To have access to SVGA graphic modes under X11, use the @code{vesa} | |
889 | X11 driver. For optimal performances, use the same depth as your | |
890 | native display. | |
891 | ||
892 | @subsection Windows | |
893 | ||
894 | If you have a slow host, using Windows 95 is better as it gives the | |
895 | best speed. Windows 2000 is also a good choice. | |
896 | ||
897 | SVGA graphic modes support: QEMU currently supports the Bochs VESA VBE | |
898 | extensions. It supports color depths of 8, 15, 16 and 32 bits per | |
899 | pixel in 640x480, 800x600 and 1024x768. For optimal performances, use | |
900 | the same depth as your native display. | |
901 | ||
902 | @itemize | |
903 | ||
904 | @item Windows XP: it should be automatically detected. | |
905 | ||
906 | @item Windows NT4 or 2000: use the driver | |
907 | @url{http://www.volny.cz/xnavara/qemuvid_bin.zip} by Filip Navara. | |
908 | ||
909 | @item Windows 95/98/Me: no clean solution yet (but it will change | |
910 | soon). You can however use the shareware driver from SciTech. Here are | |
911 | the steps recommended by Christophe Bothamy on the Bochs mailing list: | |
912 | ||
913 | @itemize | |
914 | @item install win95 with the VGA driver. | |
915 | @item download sdd 7 beta from @url{http://www.majorgeeks.com/download382.html} | |
916 | @item download pmhelp.vxd from @url{http://unununium.org/viewcvs/snap/redist/release/pmhelp.vxd} | |
917 | @item copy pmhelp.vxd to the win95 system directory | |
918 | @item install sdd7 | |
919 | @end itemize | |
920 | @end itemize | |
921 | ||
52c00a5f FB |
922 | @chapter QEMU PREP PowerPC System emulator invocation |
923 | ||
924 | Use the executable @file{qemu-system-ppc} to simulate a complete PREP | |
925 | PowerPC system. | |
926 | ||
927 | QEMU emulates the following PREP peripherials: | |
928 | ||
929 | @itemize @minus | |
930 | @item | |
931 | 2 IDE interfaces with hard disk and CD-ROM support | |
932 | @item | |
933 | Floppy disk | |
934 | @item | |
935 | up to 6 NE2000 network adapters | |
936 | @item | |
937 | Serial port | |
938 | @item | |
939 | PREP Non Volatile RAM | |
940 | @end itemize | |
941 | ||
942 | You can read the qemu PC system emulation chapter to have more | |
943 | informations about QEMU usage. | |
944 | ||
945 | More information is available at | |
946 | @url{http://jocelyn.mayer.free.fr/qemu-ppc/}. | |
947 | ||
1f673135 | 948 | @chapter QEMU User space emulator invocation |
386405f7 | 949 | |
1f673135 | 950 | @section Quick Start |
df0f11a0 | 951 | |
1f673135 FB |
952 | In order to launch a Linux process, QEMU needs the process executable |
953 | itself and all the target (x86) dynamic libraries used by it. | |
386405f7 | 954 | |
1f673135 | 955 | @itemize |
386405f7 | 956 | |
1f673135 FB |
957 | @item On x86, you can just try to launch any process by using the native |
958 | libraries: | |
386405f7 | 959 | |
1f673135 FB |
960 | @example |
961 | qemu-i386 -L / /bin/ls | |
962 | @end example | |
386405f7 | 963 | |
1f673135 FB |
964 | @code{-L /} tells that the x86 dynamic linker must be searched with a |
965 | @file{/} prefix. | |
386405f7 | 966 | |
1f673135 | 967 | @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 | 968 | |
1f673135 FB |
969 | @example |
970 | qemu-i386 -L / qemu-i386 -L / /bin/ls | |
971 | @end example | |
386405f7 | 972 | |
1f673135 FB |
973 | @item On non x86 CPUs, you need first to download at least an x86 glibc |
974 | (@file{qemu-runtime-i386-XXX-.tar.gz} on the QEMU web page). Ensure that | |
975 | @code{LD_LIBRARY_PATH} is not set: | |
df0f11a0 | 976 | |
1f673135 FB |
977 | @example |
978 | unset LD_LIBRARY_PATH | |
979 | @end example | |
1eb87257 | 980 | |
1f673135 | 981 | Then you can launch the precompiled @file{ls} x86 executable: |
1eb87257 | 982 | |
1f673135 FB |
983 | @example |
984 | qemu-i386 tests/i386/ls | |
985 | @end example | |
986 | You can look at @file{qemu-binfmt-conf.sh} so that | |
987 | QEMU is automatically launched by the Linux kernel when you try to | |
988 | launch x86 executables. It requires the @code{binfmt_misc} module in the | |
989 | Linux kernel. | |
1eb87257 | 990 | |
1f673135 FB |
991 | @item The x86 version of QEMU is also included. You can try weird things such as: |
992 | @example | |
993 | qemu-i386 /usr/local/qemu-i386/bin/qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | |
994 | @end example | |
1eb20527 | 995 | |
1f673135 | 996 | @end itemize |
1eb20527 | 997 | |
1f673135 | 998 | @section Wine launch |
1eb20527 | 999 | |
1f673135 | 1000 | @itemize |
386405f7 | 1001 | |
1f673135 FB |
1002 | @item Ensure that you have a working QEMU with the x86 glibc |
1003 | distribution (see previous section). In order to verify it, you must be | |
1004 | able to do: | |
386405f7 | 1005 | |
1f673135 FB |
1006 | @example |
1007 | qemu-i386 /usr/local/qemu-i386/bin/ls-i386 | |
1008 | @end example | |
386405f7 | 1009 | |
1f673135 FB |
1010 | @item Download the binary x86 Wine install |
1011 | (@file{qemu-XXX-i386-wine.tar.gz} on the QEMU web page). | |
386405f7 | 1012 | |
1f673135 FB |
1013 | @item Configure Wine on your account. Look at the provided script |
1014 | @file{/usr/local/qemu-i386/bin/wine-conf.sh}. Your previous | |
1015 | @code{$@{HOME@}/.wine} directory is saved to @code{$@{HOME@}/.wine.org}. | |
386405f7 | 1016 | |
1f673135 | 1017 | @item Then you can try the example @file{putty.exe}: |
386405f7 | 1018 | |
1f673135 FB |
1019 | @example |
1020 | qemu-i386 /usr/local/qemu-i386/wine/bin/wine /usr/local/qemu-i386/wine/c/Program\ Files/putty.exe | |
1021 | @end example | |
386405f7 | 1022 | |
1f673135 | 1023 | @end itemize |
fd429f2f | 1024 | |
1f673135 | 1025 | @section Command line options |
1eb20527 | 1026 | |
1f673135 FB |
1027 | @example |
1028 | usage: qemu-i386 [-h] [-d] [-L path] [-s size] program [arguments...] | |
1029 | @end example | |
1eb20527 | 1030 | |
1f673135 FB |
1031 | @table @option |
1032 | @item -h | |
1033 | Print the help | |
1034 | @item -L path | |
1035 | Set the x86 elf interpreter prefix (default=/usr/local/qemu-i386) | |
1036 | @item -s size | |
1037 | Set the x86 stack size in bytes (default=524288) | |
386405f7 FB |
1038 | @end table |
1039 | ||
1f673135 | 1040 | Debug options: |
386405f7 | 1041 | |
1f673135 FB |
1042 | @table @option |
1043 | @item -d | |
1044 | Activate log (logfile=/tmp/qemu.log) | |
1045 | @item -p pagesize | |
1046 | Act as if the host page size was 'pagesize' bytes | |
1047 | @end table | |
386405f7 | 1048 |